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.

You're right, but Raskin is wrong

[Univac_1004]

Raskin (who did not write code himself, but was more of a essayist) was a devote of "Literate Programming", first promulgated by Knuth: http://www.literateprogramming.com/knuthweb.pdf/

In "Literate Programming" the comments are all important and the code itself is trivialized. The code, as Jef told me, is like "raisons in the muffin of the comments." There are paragraphs of verbiage which might go on about the history of the project, why certain features were discarded, etc., etc, and might not even explain what the following line or two of code was concerned with.

It's really very difficult to deal with code that has been written in this style ("literatized?" ) since the actual structure of the program is severly obscured. It serves as an example of how overdoing a good thing is usually a bad thing.

Jef was a nice guy, and I recommend his book, "The Humane Interface" for its many interesting ideas. His attempt to put them into practice in the Archy project http://rchi.raskincenter.org/aboutrchi/index.php/, was not completed before his death. Even for that, Archy is very close to his vision.

But since Jef was in many ways an extremist, one can demonstrate in Archy his pushing of his concepts to the limit resulted in the end fully maching his goals. Somewhat like "Literate Programming", in fact.

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:The problem isn't lack of comments

[emurphy42]

Er, that's a nonexistent article. Fortunately, a Wikipedia search on "orthogonal" did lead to another article that does exist.

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.