[philiptellis] /bb|[^b]{2}/
Never stop Grokking


Saturday, May 17, 2008

Commenting

A discussion at work got into whether comments are good or not. I have my own opinions about comments, and years of having to dig through other people's code has taught me not to trust them too much. Comments that I've put into my code in the past have generally been stories and anecdotes that I wanted to tell future readers of my code, and seldom about the code itself.

When I have to go through someone else's code, I start off by assuming that their comments were bad and delete all but a few of them. They may not actually be bad, but it saves me the time I'd spend separating bad comments from good ones, and I can always refer to the last version in CVS if I need to check on old comments. In general, I've seen the following types of comments:
  1. Useless comments - they explain what a particular piece of code does
  2. Obsolete comments - the code changed but the comments didn't
  3. Mental notes - they explain why a particular piece of code does what it does
  4. Reminders - FIXME/TODO comments
There are also API docs that look like comments, but that's only because the comment syntax in most languages is the only way to add documentation (perl has pod though). I'll ignore this type, but you still need to be careful of API docs that don't match the API or the implementation - they're probably both wrong.

The first type is largely useless. The code is either very obvious in what it does, in which case the comment is not needed, or it's not, in which case it should be rewritten. One of the rules from the Elements of Programming Style goes thus:
Don't comment bad code, rewrite it
It's #63 if you care, while #69 says:
Don't over-comment
The next type is worse than useless, it slows you down in your understanding of the code. Delete and take note of rule #61:
Make sure comments and code agree
The third type of comment is useful in understanding a block of code and the thought process that went into it, and is also useful in knowing how to rewrite/optimise that code. Some developers may prefer to push this kind of comment out to bugzilla and link to it in the code. Either way works. I generally leave these comments around or rewrite them depending on what I'm doing to the code they affect. Rule #62 says:
Don't just echo the code with comments - make every comment count
This is how you make it count.

Reminders, IMO, are better suited to bugzilla with the bug number noted in the code. This is so mainly because bugzilla sends out reminders while your code doesn't. If I can, I'll fix the relevant code, or delete the comment if no longer pertinent (these kinds of comments tend to hang around for several years without anyone noticing).

Oh, and just in case someone wanted to counter #2 by saying that sometimes you need to write obscure code to be efficient, or because it was a smart way to do something, I present to you rules #1, #2 and #5:
Write clearly - don't be too clever
Say what you mean, simply and directly
Write clearly - don't sacrifice clarity for "efficiency"
So, have fun commenting your code, have a dialogue with your readers, or think of it as a mini blog about the code, but make sure you make your comments useful or fun. If you're interested in the quick summary of the Elements of Programming Style, grab the fortune cookie file.

5 comments :

Unknown
June 18, 2008 6:22 PM

Hey Philip

Don't know what ignited me and started surfing, searching for people linked with NCST in year 2001. One thing lead to another and finally landed on your website (you examined our C++ project back then). You are full of life!!! and your blog full of all kind of information. I am sure to visit you website to learn more from you.

Thanks
Shilpa

Philip
June 18, 2008 8:57 PM

Hi Shilpa, thanks for visiting my blog. Yeah, keep coming back, I write a lot all over the place.

Unknown
January 01, 2010 8:56 PM

There's one subtype of your type 3 comment that I think deserves special note: comments for workarounds. For example:

/* GetThingummy() has been known to cause system crashes under DoofOS 3.1, so we have to provide our own thingummy here. */

It's not there so much to clarify the code, which might be perfectly understandable without it, but to explain the context that made the code necessary, context that isn't derivable from the code itself. As such, it's absolutely essential: without it, you run the risk that someone will decide to simplify the code and get rid of the workaround.

Of course, the ideal approach is to just fix the bug that it's a workaround for, but sometimes that isn't an option -- for example, when the bug is in an operating system, or a web browser, or some other piece of code that has already been deployed to millions of desktop machines that you don't have access to. As such, how often this sort of comment is useful depends on the context. Web programmers probably need it more frequently than anyone else.

Philip
January 02, 2010 3:21 AM

@muckenhoupt Thanks for the "comment". Yes, you make a good point. For the most part, I think code that has to deal with these kinds of subsystem bugs should be in libraries. On the web in particular, browser compatibility is handled quite well in libraries such as YUI, jQuery and Dojo, so for the most part, the general web developer community does not need to worry about it.

That's not to say that these kinds of comments aren't needed, just that if we see the same kind of comment show up all over the place, then chances are that it needs to be abstracted out into a library.

Bilbo
January 02, 2010 8:44 AM

There's another class of useless comment: old code.
I worked on a program where 90% of the lines in a program were comments and 80% of those comments were commented out old code, and most of the rest were no more use - references to old documentation etc.
I'm not exagerrating, I wish I were.
On that project I wrote a macro to delete all the comments before I even looked at the code.

Post a Comment

...===...