Comments say why

Sunday 31 August 2003

There’s a thread going around about comments in source code. Christian said:

Not all comments are bad. But they are generally deodorant; they cover up mistakes in the code. Each time a comment is written to explain what the code is doing, the code should be re-written to be more clean and self explanatory.

Oliver Steele responded:

Comments are an escape hatch for expressing everything about the program that the programming language can’t.

Opening shots notwithstanding, the essays agree more than they disagree. Both decide that there are lots of important uses for comments. In my experience, it boils down to a simple distinction:

Code says what to do, comments say why.

The comments Christian is railing about in his post are probably comments that tell you what is happening. We’ve all seen the classic:

i++; // increment i

This is bad because the code already described what is happening, and the comment is simply describing it again. No new information has been added to the system. Of course in the real world, the examples are usually not so blatant.

If you find yourself writing comments that describe the “what”, think about whether you have an expressive-enough coding style, or whether you need richer primitives, or a more directly applicable framework. There may be ways to change your coding so that the “what” is adequately covered by the code. Then you can focus on the “why” in your comments.

BTW: Christian also covers the writer’s difficulty of understanding their audience from a commenter’s point of view in his followup post.

Comments

[gravatar]
Ben Langhinrichs 7:16 AM on 31 Aug 2003

I'm sorry, but I have been watching the "comments are bad, code should be self-documenting" argument for about a quarter of a century (yikes!), and it is ridiculous. It leads more often to convoluted code that tries too hard to be documentation and too little to be good code. Of course, variable names and function names should be descriptive and so on, but code is meant to do a job well, not play two roles. Sometimes a really good piece of code is not the least bit self explanatory, and comments are a better answer than re-writing the code.

I guess the basic tenet that code should be the "what" and comments the "why", but even that assumes that the "what" may be obvious. Most of the time, yes, but sometimes even the what of what is happening must be explained, since some kinds of code are too densely packed for clarity, yet serve a need which should not be compromised due to a distaste for comments.

[gravatar]
David Bailey 9:21 AM on 31 Aug 2003

This argument has been going on for a long time.
Kernighan & Plauger's "Elements of Programming Style," 1974, said something to the effect, "Comments are an apology for bad code."

[gravatar]
Laurent 1:26 AM on 1 Sep 2003

Thanks for your simple rule. I was searching that for quite a while. It is like watching the start of a crystallization, the rigth conditions and everything is crystal clear.

Laurent

[gravatar]
Martijn 4:05 AM on 1 Sep 2003

Personally I would much rather have extensive comments in the code explaining why it's doing what than to have some documentation outside the code (that always gets lost somehow). Are you going to look in the code or in the DFD's, ERD's or whatever other diagrams when a problem occurs and you have to find out what is causing it.

[gravatar]
Jim 8:04 AM on 1 Sep 2003

Sorry, comments are good. Of course you can get _bad_ comments, but as long as they are used properly, they are a godsend. There's just too many times where you need to work around an obscure bug that only appears on certain platforms or something, and need a note to the effect of "don't simplify this in the obvious way because it will break on [x]".

[gravatar]
Richard Schwartz 10:16 AM on 1 Sep 2003

Like Ben, I've been following this argument for a long, long time, and I agree with Ben. Typical application code these days is often a long series of calls to an API of some sort. With the level of complexity of many of the APIs that we have to deal with every day, and the rapid rate of change of underlying technologies that we keep ourselves current on, we must not assume that a maintenance programmer two years down the line (even if that programmer is going to be ourself!) is going to still be fluent in the details of that API. Comments need to point out those details that aren't immediately obvious. At an absolute minimum: if you had to look it up yourself, or you had to try a few test cases yourself, or you had to examine some test data in order to figure out how to write the code -- it deserves a clearly written comment in the code. A better standard would be to make the call based not on what you would have to do, but on what the least experienced member of your team would have to do in order to write the code.

Also, in addition to the why, comments should also say why not! I.e., if your first read of the API documentation suggested that you might be able to write the code one way, but you found out along the way that there were complications so you had to do it another way, you should comment not just what you did, but what you didn't do and why you didn't do it!

-rich

[gravatar]
Ben Langhinrichs 10:40 AM on 1 Sep 2003

Rich makes a good point, especially about the "why not", which is often what I comment the most.

[gravatar]
Tom Duff 12:23 PM on 1 Sep 2003

I'm usually accused of overcommenting (and I admit it). My rule of thumb is to comment my intent. If you work with great programmers, maybe you don't have to do that. But in a typical company, you have everything from gurus to newbies who may touch your code. If the newbies can use the comments to understand what a better programmer is trying to accomplish, great. I recently finished a stint at a client where a beginning Notes developer took over maintenance of applications I had done for over a year. With few exceptions, he was able to read and understand the LotusScript code I wrote even without knowing the language, because I had commented what was going on... I consider that a success.

[gravatar]
Ben Poole 3:44 PM on 2 Sep 2003

I over-comment when the code is for a newbie. Otherwise, my comments are quite brief: "why rather than what" is a pretty good rule I'd say.

I also like to use "headers" for each sub / function / whatever within a larger app that details dependencies and what-have-you.

Add a comment:

Ignore this:
Leave this empty:
Name is required. Either email or web are required. Email won't be displayed and I won't spam you. Your web site won't be indexed by search engines.
Don't put anything here:
Leave this empty:
URLs auto-link and some tags are allowed: <a><b><i><p><br><pre>.