What is your personal approach/take on commenting?

Question

Duplicate

What are your hard rules about commenting?

A Developer I work with had some things to say about commenting that were interesting to me (see below). What is your personal approach/take on commenting?

"I don't add comments to code unless its a simple heading or there's a
platform-bug or a necessary work-around that isn't obvious. Code can change and comments may become misleading. Code should be
self-documenting in its use of descriptive names and its logical
organization - and its solutions should be the cleanest/simplest way
to perform a given task. If a programmer can't tell what a program
does by only reading the code, then he's not ready to alter it.
Commenting tends to be a crutch for writing something complex or
non-obvious - my goal is to always write clean and simple code."

"I think there a few camps when it comes to commenting, the enterprisey-type who think they're writing an API and some grand code-library that will be used for generations to come, the craftsman-like programmer that thinks code says what it does clearer than a comment could, and novices that write verbose/unclear code so as to need to leave notes to themselves as to why they did something."

Answer 1

The vast majority of my commnets are at the class-level and method-level, and I like to describe the higher-level view instead of just args/return value. I'm especially careful to describe any "non-linearities" in the function (limits, corner cases, etc) that could trip up the unwary.

Typically I don't comment inside a method, except to mark "FIXME" items, or very occasionally some sort of "here be monsters" gotcha that I just can't seem to clean up, but I work very hard to avoid those. As Fowler says in Refactoring, comments tend to indicate smally code.

Answer 2

I prefer to use "Hansel and Gretel" type comments; little notes in the code as to why I'm doing it this way, or why some other way isn't appropriate. The next person to visit this code will probably need this info, and more often than not, that person will be me.

Answer 3

Sometimes code does exactly what it needs to do, but is kind of complicated and wouldn't be immediately obvious the first time someone else looked at it. In this case, I'll add a short inline comment describing what the code is intended to do.

I also try to give methods and classes documentation headers, which is good for intellisense and auto-generated documentation. I actually have a bad habit of leaving 90% of my methods and classes undocumented. You don't have time to document things when you're in the middle of coding and everything is changing constantly. Then when you're done you don't feel like going back and finding all the new stuff and documenting it. It's probably good to go back every month or so and just write a bunch of documentation.

Answer 4

Most of the time I find that the best comment is the function or method name I am currently coding in. All other comments (except for the reasons your friend mentioned - I agree with them) feel superfluous.

So in this instance commenting feels like overkill:

/*
 * this function adds two integers
 */
int add(int x, int y)
{
    // add x to y and return it
    return x + y;
}

because the code is self-describing. There is no need to comment this kind of thing as the name of the function clearly indicates what it does and the return statement is pretty clear as well. You would be surprised how clear your code becomes when you break it down into tiny functions like this.

Answer 5

If the code is not clear without comments, first make the code a clearer statement of intent, then only add comments as needed.

Comments have their place, but primarily for cases where the code is unavoidably subtle or complex (inherent complexity is due to the nature of the problem being solved, not due to laziness or muddled thinking on the part of the programmer).

Requiring comments and "measuring productivity" in lines-of-code can lead to junk such as:

/*****
 *
 * Increase the value of variable i,
 * but only up to the value of variable j.
 *
 *****/

if (i < j) {
    ++i;
} else {
    i = j;
}

rather than the succinct (and clear to the appropriately-skilled programmer):

i = Math.min(j, i + 1);

YMMV

Answer 6

While I agree that code should be self-readable, I still see a lot of value in adding extensive comment blocks for explaining design decisions. For example "I did xyz instead of the common practice of abc because of this caveot ..." with a URL to a bug report or something.

I try to look at it as: If I'm dead and gone and someone straight out of college has to fix a bug here, what are they going to need to know?