I had some horrendously complex code to compute the two roots of a quadratic, and someone came along and "tidied it up." They replaced my code with:

  delta = sqrt(b^2-4*a*c)
  a2 = 2*a
  x0 = (-b+delta)/a2
  x1 = (-b-delta)/a2

He put it back and all was well, then came to ask me about it. I explained about numerical stability, and all was well.

So with regards comments:

Pro: He would've known not to change the code, and it was complicated for a reason.

Con: He wouldn't've come to me to discuss why it was a problem, and hence wouldn't've learned about numerical stability.

Gripping hand: With a comment he would've known why, and the time wasted changing the code, testing, investigating and putting it all back would've been saved, and better spent learning about numerical stability, which he then had to do anyway.

I'm in favor of the correct use of comments, and YMWV as to what that means. Dogma is the enemy of true progress.

An often stated rebuttal to the above is that the developer can comment the "complicated bits", and save time by skipping it the rest of the time. This is a flawed argument -- you don't know if you need to write a comment for a block of code until you've spent the time fully considering what needs to be commented ... which takes just as long as writing a comment.

This holds doubly true for APIs. Any time that your future API clients spend reading your source code instead of skimming your documentation is wasted time. Additionally, deriving guarantees and invariants from the source code does not make them true -- the invariants could be changed in the future, as there's nothing in the code to document what should be, instead of what currently is.

"Comments are unnecessary" is just an excuse for lazy developers to be lazy, and thus leverage externalities to reduce their upfront workload in exchange for increasing the workload and complexity for the programmers that follow them -- which may, in fact, be themselves.

Additionally, commenting every bit of the code, especially as you go along, leaves one prone to forgetting the most important reason to comment: explaining the rationale for what you're doing. Explaining the design decisions in comments (and especially why you didn't do the alternative) is invaluable, and much more accessible to a maintainer (such as oneself a few months later) than an external design document.

I HATE code with no comments. And tests are not sufficient documentation, though that's an argument for a different time.

Usually, I'm looking for general readability and understandability. I'd much rather see short, well-named classes and methods, well-named variables and good unit tests before I see a single comment.

In the absence of clean, readable code, comments are probably a reasonable but nevertheless inferior resort. I also agree that, sometimes, they 'why' of code is often best expressed as comments.

When working with legacy code that is not commented, how do you determine the invariants of an API?

That is, how do you ensure that the change you're making will not break other code? Do you have to scan the entire project, and any other projects that depend on it?

Unit tests are often not sufficient here -- changing the invariants of an API may not result in deterministic failure -- in fact, invariants often describe requirements necessary for deterministic behavior.

Ha ha ... also don't waste your time asking me for a job.

I imagine, also, that a fair collection of idiots also start using it as an excuse not to bother commenting their illegible code, but they seem to keep quiet about it.

The author points out that "Sometimes you just need to leave a note", but that doesn't stop people coming out and declaring it "the most retarded article ever". These are people who can't tell the difference between "Never write comments" and "Write clean code to avoid the need for comments".

Even as I write this, I imagine some of them bursting a blood vessel because "You can't always avoid comments".

I agree, you can't. If (for example) you are authoring some workaround for a counterintuitive 3rd party API, then yes, good commentary is important.

However, if you write short, well-named, DRY, SRP-obeying units, with well named parameters and variables, and well-named, clear tests, then many of the comments that you find in poorly written code simply aren't needed any more, because they are there in the code itself.

Let's not forget that writing comments and notes is not unique to computer programming. Most professions, law, medicine, must create notes, and comments to understand the work at hand. Those who don't, or refuse are looked at as lazy and unprofessional.

I don't want notes for every single line of code, but for sections of complicated code comments are a must for ease debugging, or future modifications.

Many times developers write shitty code, put a stamp of "it works" on it and then comment it, as if comments make it OK. Bullshit. Perfect code doesn't need comments. We can't achieve perfection, but we can try.

E.g., I was recently writing for a JPA entity on Google App Engine where I tried using a @PrePersist function to update a field. Turned out that GAE won't call the @PrePersist unless a field is updated first...i.e., catch 22.

So, say as a workaround you add an artificial update to the field to null just so your @PrePersist is called, what are the odds that the next guy reading the code without a comment won't just delete that assignment thinking it's unnecessary?

* You have tests.

* People write code to be readable.

Where I work, neither is the case. I try to write tests[1] for my stuff, and I try to write clearly. But I have to comment what I'm doing since the libraries and APIs I'm calling are so baroque and almost deliberately obfuscated, that I have to comment what's going on if for no other reason than self defense.

[1] As a point of reference, in my current project we have something like 6 - 8 developers. Of the unit tests that exist, I've written 85% of them, and I'm embarrassed at how few I've written.

It was always explained to me in this way: code describes what is done, comments describe why it is done. Code cannot explain the second, and comments should not explain the first.

However, I agree that what you say is certainly true of APIs.

As I'm sure will be repeated over and over, comment the why, not the what or the how.