/*How to Read a Comment*/
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Everybody knows that you're supposed to write comments in your code. The problem facing maintenance programmers is this: Once the comments are written, can they be read?
Comments are one of the most idiosyncratic parts of a programmer's style. Compilers will spot all sorts of code errors, but comments are completely unchecked. The programmer has presumably tested whatever code you're looking at, and it worked—at least for some limited test under some circumstances in the past. But the comments could be bald-faced lies, half-truths, or simply out of date. Many programmers often choose to ignore the comments entirely, in favor of reading the code.
Reading Code
A few years ago, a sign appeared around the MIT Athena computer lab proclaiming, "You must be at least this smart to use Athena workstations," with an arrow pointing to the right side of a bell curve.
I sometimes wish that I could put that sign into my code. Sometimes a chunk of code requires understanding a set of background techniques that are simply impossible to explain in a comment. For example, I write recursive-descent parsers quite often, and I'm not going to explain how they work each time I use them. I've seen comments that say things like this:
// If you don't understand this, // please don't touch this code
Of course, it would be better for the code writer to explain where the astute code reader can get the information he or she needs, by referencing a web site or textbook. If you encounter a comment like this, it's probably necessary for you to do a lot of background reading before touching the code. Or maybe you've just encountered an arrogant programmer who thinks he's a lot smarter than you, in which case you proceed at your peril.
Sometimes comments are just useless, like in this example from a major piece of open-source software:
// cycle through given args for (int i = 0; i < args.length; i++)
If you're reading this particular piece of code, you'd better be able to figure out what the for loop does. Beware of such comments, because it's a signal that other comments in the code may be equally unhelpful. The more comments there are, the more work you have to do to maintain those comments.
As a maintenance programmer, it's not your position to delete this comment, because of the following principle of maintenance programming: Tread lightly. Which means that you don't make any changes at all unless they're absolutely necessary. In this case, the comment is a helpful signal about the rest of the developer's style. Unless you intend to completely rewrite all the comments, just leave it there as a warning to the next maintainer.