From the author of

From the author of

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.