Whom Do Comments Help

Much has been said about comments, how they can be presented and where, what they describe and why some part of a program exists or performs.

Since QuestionsMakeGoodPages, I ask, "Whom does a comment help?"

Does it help the programmer, and if so, when? Is it meant to help in construction or is it meant to help another programmer or the originator when the code needs to be revisited?

Is a well-documented program one which has a lot of comments, or one which comments sparsely and thoughtfully? Is a comment written by someone who did not write the code, but feels the need to explain things which do not have MeaningfulNames?

Could handwritten notes on an archival copy of a program be more helpful than those which have been painstakingly added to the source code, never to be seen for years, if ever at all?

I really want to know - in the experience of those who have adopted some sort of commentary on or about their own programs, whom have you written your comment for?

Other than comments intended to drive JavaDoc or equivalent, I write comments for the benefit of the next developer who might encounter my code, which could be me or someone else. My comments are typically:

Explicit hints or reminders for future refactoring or enhancements;
Clues as to the behaviour of unintuitive code (which often makes them effectively a refactoring hint);
Hints about method parameters. E.g., "Pass a null to 'theFoozle' to generate a new default foozle inside florg()."
Clarifications about method arguments. E.g., "We're passing a null to the third parameter so florg() will generate a new default foozle."
Clarifications of quirky code needed to deal with someone else's poorly-designed APIs, libraries, etc. E.g., "We have to call SpoogeLib.foobulate() here instead of inside the glarbification method because SpoogeLib throws an exception if we use foobulate() inside a glarbification context."
Indications of intent, i.e., an indication of why rather than how. E.g., "Sort the fleegles in the splork container here because flarg() expects fleegles in piff order, but sorting them inside flarg() would cause flarg() to run too slowly."

Obviously, one of the goals of refactoring is to make the code self-documenting and reduce comments like the above.

To me, well-commented code is that which contains just enough commentary to enhance readability, but not so much that it obstructs it.

Handwritten notes on archival copies would only make sense if there were archival print-outs. I haven't made such a thing in decades. Archives are kept in files on multiple hard drives and digital backup media.

-- DaveVoorhis

The only time I've seen handwritten notes on printouts is as part of a CodeReview - I've found it helpful to print out the code in question so it can be scribbled on during the review process, even if the code is being read onscreen. [See also IsAnythingBetterThanPaper.] -- EarleMartin

I always find it strange that proponents of comments always assert that they help someone else, but I have never seen a report of someone saying, "This comment helped me."

The following are cynical, but true, areas where I have benefitted from comments.

When trying to trace through some hard to understand code, I would write comments rather than change the code. If the comments were in files that I did not later change, they were usually lost due to concerns about making unnecessary changes to the code.
Other developers would gush over my commenting style. There was never any indication that they actually had to work on the code, but the print outs looked nice.
In examples published in internal guides and books. These comments often related to style issues or other information that was not needed for production systems.

I've been helped by comments several times. There have also been several times where I've been staring at a 40k-line codebase and wishing that the author had bothered to write in at least some comments.

The types of comments I usually write:

"Why" comments that explain why I chose a particular (sometimes unintuitive) approach. Usually these have to do with corner cases in the problem specification which you wouldn't immediately think of.
ToDo comments for features I want to add or generalize but don't have time for now.
Flags that code is a hack and ought to have a more elegant solution, but I don't know what that solution is. This is basically a ToDo comment (and I often mark it as such); it hints that the code should be refactored later.
Knowledge about the behavior of third-party libraries and products that was discovered laboriously through a debugger, mailing list, or inspection of the source code. Often it takes days to track down these sorts of bugs, and I don't want to have to do it multiple times.
Assumptions I make about the behavior or capabilities of third-party language/library features. This is a way of showcasing my stupidity for future developers: if they can see, outright, that I'm wrong, they're free to refactor the code to use the right approach. Also, libraries tend to gain features over time; oftentimes, the hack I wrote 3 years ago has been obsoleted by new features in the latest version.

JavaDoc is a different beast entirely, because it's intended for the library user rather than the library developer. However, I'll say that the biggest productivity enhancer I've found is adequate, well-organized documentation. The Java standard libraries are great at this, but most frameworks and libraries are terrible. Judging from where I spend my time nowadays, my productivity would multiple 3-4 times if every library had the same quality documentation as J2SE. -- JonathanTang

Would you care to expand on the first statement and describe comments that have helped you?

I'm not JonathanTang, but I can illustrate a comment that helped me. Here's some code from the collision detection code in a simple game I use for teaching game AI, sans comments:

public Tanq getCollider(Bullet b) {
Iterator i = tanqs.iterator();
while (i.hasNext()) {
Tanq t = (Tanq)i.next();
if (t == b.getOwner())
continue;
if (b.isTouching(t))
return t;
}
return null;
}

Is it immediately intuitive why the following statement exists?

if (t == b.getOwner())
continue;

Here it is, with the comment that I found useful when I was reviewing the code this morning:

public Tanq getCollider(Bullet b) {
Iterator i = tanqs.iterator();
while (i.hasNext()) {
Tanq t = (Tanq)i.next();
if (t == b.getOwner())    // can't be shot by own bullets
continue;
if (b.isTouching(t))
return t;
}
return null;
}

With the comment, I can immediately see why I put in the statement.

The comment is both an explanation that is helpful to me right now, and it is a refactoring hint. Later, to slightly improve readability, I might change the code to this...

public Tanq getCollider(Bullet b) {
Iterator i = tanqs.iterator();
while (i.hasNext()) {
Tanq t = (Tanq)i.next();
if (b.isMyOwnBullet(t))
continue;
if (b.isTouching(t))
return t;
}
return null;
}

...but even with the above, I might leave the comment in place because it explains the policy that the statement implements.

-- DaveVoorhis

Part of the problem is that comments detract from readability once you are familiar with the code. Shameful that IDEs don't have a global toggle to show/hide all comments.

Visual Studio 2005 does. It's Ctrl+M, L.

Eclipse 3.2 will. See http://download.eclipse.org/eclipse/downloads/drops/S-3.2M1-200508111530/eclipse-news-M1.html under "Additional folding commands."

Other IDEs will, no doubt, follow.

See also http:wiki?search=Comment (there are quite a few)

CategoryCodingIssues