"I don't mind working with your code, because at least you comment it"

My first nomination for the 'justifiable homicide' defence would be a comment made by a fellow programmer, upon being given a small project of mine to finish while I was away on holiday. Actually it wasn't this comment, so much as the sheepish admission which followed that he hardly commented his own code.

Ah yes. In-line documentation. We all know we should do it. We all claim that we do do it. But, let's have a show of hands, how many of us really do it (properly)?

Exactly! (And no, Javadocs don't count. Just in case you thought you could get off lightly. They document the API from an external viewpoint, they don't document the internal implementation and mechanics.)

All too often I find myself looking through source code were the number of comment lines can be counted on the fingers of one hand. Indeed it is too frequently the case that the number of genuine comment lines is heavily outnumbered by the number of source code lines left commented out.

Back when I was at college one Computer Science lecturer requested the class each supply one printed example of a short program they had written, in any language, minus everything except the in-line comments. He shuffled and re-distributed the print-outs, and told us we had twenty marks each to start with. Every time we found a comment which betrayed which programming language the code had originally been written in, we had to knock off a mark. Every time we found a comment which merely parroted the code ("Add 1 to x") we had to knock off a mark. And so on...

As well as being a light hearted exercise (nobody scored more than five, with most people skulking in the negative numbers) it served to re-enforce an important point about commenting source code. Specifically: what to comment, where, and how much!

The golden rule, we were told, was that code should be commented sufficient that a fellow programmer could re-implement your algorithm in a totally different language from the comments alone. Excuses like "oh, but the code is self documenting" simply didn't cut the mustard (whatever that actually means!) The code explains to the compiler what should actually happen, while your comments explain what you (the author) think is happening.

(Yes YOU -- the weakest link in the chain! The fool who causes all the errors! The real culprit behind the phrase "computer error"!!)

# Make sure the key is all digits
if($key =~ /[0-9]+/)

The above is a reconstructed fragment of a web script I had the misfortune to debug some time back. The entire script contained only two comments, the first acknowledged the script's author and creation date, while the second documented a regular expression. As you can see, code and comment don't quite tally.

I wasn't specifically looking for this bug -- indeed thus far the bug had never manifested itself, so nobody was looking for it -- but thanks to that one single comment my attention was drawn to that odd section of code, and after careful examination I was able to rectify the problem before it even emerged.

These days it seems the push is for cleaner, simpler, less error prone methods of working. From the language syntax, to methodologies, to testing, there has been a renewed focus on minimising the potential for human error, and maximising the chance of trapping errors when they occur. About time too! But it is ironic, perhaps, that the most powerful tool for preventing and trapping errors is to simply get the author to write a plain English description of what she thinks the code is supposed to achieve to accompany each step of the algorithm (along with any noteworthy observations -- "does minimal error checking" or "not thread safe", for example.)

But how many bother with anything other than terse one liners? Or simply don't bother at all?

We're all guilty of being a little sloppy with when it comes to explaining our reasoning. Certainly I have to hold my hand up and admit I've written a few bits of code which have been decidedly thin in the in-line documentation stakes. We've all done it. But that doesn't make it right, and it doesn't mean it should be treated as the norm rather than the exception.

Taking that extra sixty seconds to provide a human-readable description of that morsel of code you're working on not only gives unfamiliar eyes a fast track to understanding your code, but also helps to rationalise your thinking (you'd be surprised how many flaws you find when you are forced to commit an idea to text) while affording colleagues a opportunity to spot discrepancies between what you wanted to do and what your code actually does.

All those guilty of not commenting their code should now line up against the wall, blindfolds at the ready. (Me too, I guess!) The programming firing squad will be here shortly, just as soon as they finish documenting their three-step procedure. :)