Comment On This

So the other day I'm looking over some code, and I see this... (slightly paraphrased to protect the innocent -- in the original, the declaration and the getter were, of course, separated.)

/**
 * The name of the user
 */
private String m_userName;

/**
 * @return The name of the user
 */
public String getUserName() {
    return m_userName;
} 

And I thought, "I really hope some of that was generated by the editor"

And then I thought, "This is why other languages make fun of Java"

And I finally ended up with, "Most of what beginning programmers are taught about comments is useless". At least that was true when I was in school.

For the moment, I'll put aside the Java issue, to talk more generally about comments.

First though -- we're agreed the example is absurd, right? In that it repeats that the user name is, in fact, the user name five times. Which is at least four more than strictly necessary (I realize that Java more or less forces some of this duplication).

I realize that this is hardly the worst coding sin you can commit, but when I look at code like that I do think that either the programmer isn't quite sure which parts of his code are most important or that the person is rigidly following an overly formal standard. Neither of which is all that flattering.

About 95% of the time, it seems like you either get no comments, or the kind of useless comments in the example. Given the choice, I'd rather have no comments -- it's less distracting, and you can see more code at once.

However, you can do comments effectively. Here's what I think, which should not ever be confused with what I actually do.

• The best commenting is clear and accurate names for your variables, functions, and classes.



• The "No Duplication" rule applies to comments at least as much as it does to code.



• Possibly more, since no compiler is ever going to catch if your comments fall out of sync with your code.



• Therefore, under normal circumstances, comments should avoid repeating what the code does.



• However, limitations on input or output values that are not apparent from the code should be included in comments. If the user name was guaranteed to be under ten characters because of the underlying database, that would be a useful comment.



• Rationales for choosing a particular implementation are often good comments, as is the code's place within the larger program.



• If you find yourself commenting inline within a long method to explain what the next section does, odds are you'd be better of extracting that to a well-named method and skipping the comment.



• There is a cost to commenting -- it takes time to do well, and it can be distracting. It also limits the amount of code you can read at once.



• The most obvious exception to all of the above is when you are in a situation where people will read your comments without ready access to the source code. Writing an API or a framework, for example. In that case, most of the issue about duplication doesn't apply and you need to be descriptive for the benefit of users who will only see your JavaDoc or RDoc.



• However, none of that excuses writing a one line comment for getUserName().