Judging from the abstract of the paper you link (the content’s paywalled), they seem to include API and method comments as well as the in-code comments I was specifically trying to address.

I’m speaking from experience, not hearsay or myth propagation, when I say that comments get stale in almost every piece of code I see. For instance, another message that arrived in my e-mail today is about the API drift and stale comments in the API doc for the C++ Matrix library Eigen. Last week, I sent the Eigen developers comments about stale abstract base class doc in an obscure corner of their API. I’m not picking on Eigen, which is a great lib and very well documented and testedl. The point is that I had to dig into the code to see how to extend a virtual class properly to act as a template arg.

We don’t live in a perfect world where everything is immediately clear; we don’t live in a perfect world where every programmer on a team actually cares or has the ability to write crystal clear code; we don’t live in a perfect world where every bit of code we write will be so clear that it documents itself. We don’t have perfect memories that never forget what we were doing the day before or why we chose a certain method of doing something over another. Comments help with this!

The that gets me is that the people saying ‘no comments’ haven’t done any real research into the topic. For example, what state is your mind in when reading code (i.e. variable names and unit test)? What state is your mind in when reading natural language? Which do you comprehend more easily? I know that when I read code my mind isn’t in the same state as when I read natural language prose. Also, research (REAL LIVE RESEARCH — novel isn’t it) indicates that programmers are pretty good at updating comments when code changes.

http://portal.acm.org/citation.cfm?id=1339530

Could we stop propagating this lie please?

I’ve never had second thoughts about this. As I’ve spent more time programming, these comment blocks have become more typical of code I write.

For the easy stuff, I agree, better to restrict to API comments, gotchas, loop invariants — key bits.

Suppose I want to ignore all objects that have some attribute smaller than a particular value

if (foo.stuff < 3)
ignore(foo);

I can rewrite this to

val StuffThreshold = 3;

if(foo.stuff < StuffThreshold)
ignore(foo);

or

def isBad(foo : Foo) = foo.stuff < StuffThreshold

if(isBad(foo))
ignore(foo);

You could argue that this is more clear. I don't particularly think it is, but I don't care to have that argument. Either way it's certainly not done anything to enlighten us about why the value "3" was chosen, and for good reason: It was derived experimentally.

Your argument presupposes exactly the reason why it is wrong: Not all values have "meaning" other than "this is the value that works". Comments which explain what happens when you twiddle these values and why this particular one has been chosen. Factoring out this supposedly "unclear" code has done nothing except go to great lengths to elucidate the bit that was obvious (what the code was doing) and nothing to explain the process by which it was arrived at.

I didnt’ realize this was a recurring theme on developer blogs, but I wouldn’t be surprised.

Just to be clear, I didn’t mean to imply that method names can’t lie. I meant the code itself can’t lie. You have to be just as suspicious of method names as comments.

Also, I’m all in favor of documenting intent. I’m pretty sure we’d all agree that the main intent of a package, class or method should be documented in the API.

So what about really tricky bits of code that aren’t clear (and either can’t be refactored due to efficiency/modularity, or aren’t worth refactoring)? By all means, comment away.

I didn’t mean to imply that code shouldn’t be commented at all! Maybe it was the marketing department’s provocative title?

I actually think the code that Sun distributes with the JDK for most of the public classes in Java is a good example. You’ll find very few comments in there. Now having said that, I’m actually seeing many more in java.util.ArrayList than I remember seeing anywhere else. Ditto for java.lang.String. Many more than I’d likely use, but nothing of the silly or completely useless variety. On the other hand, java.lang.Math has all sorts of comments on delegation that fall into what I’d consider the totally useless category:

public static double pow(double a, double b) {
    // default impl. delegates to StrictMath
    return StrictMath.pow(a, b);
}

Here is the comment he made on the blog:

I fired up the RSS reader this morning and spotted a real gem, “The Futility of Commenting Code”. By “gem”, I mean a piece of dirt that has been buried for a damn long time. OK, it hasn’t been buried yet but it should be.

Every month or two, if you subscribe to DZone feeds, you will see a blog post or article that explains why you shouldn’t comment your code. This post was one of them but they all need to be refuted. My irritation at this recurring theme has led me to be a refuter via this blog. I could have commented on the OP but I reckon this rant may last a while.

Let’s take it from the top…

Professional coders don’t comment their own code much and never trust the comments of others they find in code. Instead, we try to learn to read code and write more readable code.

I never get the read-the-code argument. Code that others wrote, and probably code you wrote yourself twelve months ago, can be hard to read. Other people have different styles to you. I like short, well-named methods. It means that what some developers might code in a twenty line method I may put into four five liners or five four-liners. Now, when Mr Maintenance-Programmer looks at my code I hope he finds it easy to read and specifically, to understand the intent. However, he didn’t spend months working with ABC plc and doesn’t understand the inner workings of project accounting so maybe he doesn’t get it. He could spend five mintes reading the code (or perhaps a lot longer in a large codebase), following the possible flow of control of multiple methods and struggling with the rule of seven. He could also read a one-line succinct comment and realise that that this isn’t the code he is looking for.

The reason to be very suspicious of code comments is that they can lie. The code is what’s executed, so it can’t lie.

Wanna bet? I’ve seen plenty of code that isn’t maintained properly that lies. Sometimes when the pressure is on and potential lawsuits are building, management insist on quick fixes. That often means that that wonderfully-named method now does something that really belongs elsewhere. Of course, when you are doing quick-and-dirty fixes you could edit a hundred methods. When you come back and refactor ninety-eight of them you are left with method names that lie. Yes comments can lie too, but only if you treat them as second-class citizens. Maintain your code, maintain your comments. Problem solved.

Another common reason is that the code author didn’t actually understand what the code was doing, so wrote comments that were wrong.

Maybe if you had commented that code he wouldn’t have had to read and misunderstand it.

The worst offenses in the useless category are things that simply repeat what the code says.

Ah yes, good old // Set i to 3. Personally I have never seen such an inane comment in production code. If I did, I would remove it and talk with the developer who put it there in the first place (unless he has resigned and gone off to pursue his gardening passion). This is a straw man argument, not a sensible one. Comments are suppose to tell you the intent of the programmer – something often not present and maybe impossible to express in the code. Or maybe to tell you why that apparently inefficient code is good because it avoids a framework bug (and which version of the framework because maybe it’s been fixed now).

Eliminate, don’t Comment Out, Dead Code

Good point, though sometimes leaving the dead (or maybe still twitching) code in there can be useful. At least until you have the new code living breathing and tested to within an inch of its life. Then stamp on the old stuff and hit Del before your next check-in.

This all feels a little bit like the wrong type of laziness. Some laziness is good. It’s the reason we have cars, planes, ships and bad air quality. OK, perhaps the air quality argument is a tricky one to win. Bad laziness means that software isn’t documented, there isn’t a help file, the code isn’t well-structured and is hard to read and uncommented. You just need to treat comments as a part of the source code and ensure you update them. If, like me, you have short methods, it’s not even as if the comments are off the screen so get missed.

So why did I write all this?

Some programmers are very vocal in their expression that comments are bad and shouldn’t exist at all. They probably really mean that most comments are a waste but some are good. Even the author of the OP mentions that he does comment occasionally. Bad comments are as bad as bad code. Good comments improve the code and increase efficiency. This topic is not, at some would reason, black and white.