Comments are More Important than Code

CowboyRobot writes "I was going through some code from 2002, frustrated at the lack of comments, cursing the moron who put this spaghetti together, only to realize later that I was the moron who had written it. An essay titled Comments Are More Important Than Code goes through the arguments that seem obvious only in hindsight - that 'self-documenting' code is good but not enough, that we should be able to write code based on good documentation, not the other way around, and that the thing that separates human-written code from computer-generated code is that our stuff is readable to future programmers. But I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized. Who's right?"

Comments

Raskin

[kebes]

JEF RASKIN, professor of computer science at the University of Chicago, is best known for his book, The Humane Interface (Addison-Wesley, 2000), and for having created the Macintosh project at Apple. He holds many interface patents, consults for companies around the world, and is often called upon as a speaker at conferences, seminars, and universities. His current project, The Humane Environment (http://humane.sourceforge.net/home/index.html), is attracting interest in both the computer science and business worlds.

For those who don't know (which apparently includes whoever is in charge of the linked article), Jef Raskin passed away this february. You can view the official press release, or read more about his contributions to computer science. I don't know when the article was written, but it seems it should mention that Raskin has passed away. In any case, his advice about commenting is good, just as his advice on user-interface design has always been lucid and helpful.

Comments Should Reflect Intent

[Bob9113]

I found the following in some production code, which quickly and concisely demonstrates why many comments are highly questionable:

/** Always returns true. */
public boolean isMagilla() {
return false;
}

That's the core problem with many comments, but it can be avoided. Comments are good when they state the intent or business case for a block of code, acting as a guide to the meaning of a block for subsequent developers. They are bad when they profess to know the actual outcome or implementation of a block; only the code itself can accurately reflect the state of the code.

The above would be far more useful like this:

/** Tells whether this instance meets the magilla criteria. */
public boolean isMagilla() {
return false; // currently, no MyClass meets the magilla criteria.
}

Now the intent of the method is clear, and anyone coming along who wonders why it's hard coded will know under what circumstances they should change it to a formula (namely, if MyClass becomes capable of meeting the Magilla criteria).

Comments can be good, but they should always be a guidepost to the intent of a block of code, and not attempt to explain how the code achieves that goal.

Re:Even more annoying...

[Anonymous Coward]

in vim, with C code, you can just do:

gg=G

and it will reindent a file for you....

I hate programmers who refuse to learn about their tools.

Re:Gotta document that code...

[Jeremi]

x = x++; // add one to x

is obviously not useful

Not only is the comment not useful, it's factually incorrect... the behaviour of that line of code is undefined.

Re:Top Ten Code Comment Do's List

[HomeworkJunkie]

We comment all functions and classes using the Doxygen format. This means that the comments can be used to generate HTML, PDF or man pages for the functions and classes. It will also generate call trees if required. Very useful.