Re: The Last Word on Comments (was Re: Hungarian notation)

[dewar@cs.nyu.edu (Robert Dewar)]

Jeff said

"And I am not at all convinced that "comments are ... at greater
liability in this".  When the program's behavior seems to disagree with
a comment, the comment is easily written-off as probably incorrect."

Generally I agree with Jeff, but I do not quite agree with the above. If
the comments and a programs behavior in respect to these comments do not
agree, then the program has a bug. The bug may be bad comments or it may
be bad code, you can't tell a priori, and it is a mistake to assume the
code is right *even if the program is 100% reliable and correct in terms
of its execution behavior*. 

We have all seen cases of cancelling bugs in programs, where two pieces
of code violate their specs (and hence commens), but the bugs cancel out.
I would say that although such a program is correct in a formal sense,
it has two bugs in it, and they need correcting, and in this case the
commens are right and the code is wrong.

The problem comes during maintenance when some bright programmer fixes
one of the two bugs, or uses one of the two pieces of code without the
other. This kind of emergence of latent bugs is one of the most
worrisome aspects of maintenance programming, and is a good reminder
that the intended behavior of a program internally is not neccessarily
modeled by its actual behavior *even if the program is completely
correctly operating*. So you cannot tell the intent of a piece of code
just by looking at the code even if you know the program is correct
(in the formal sense of the term, i.e. the entire program meets its spec).

In such cases, comments can be invaluable in figuring out the intent.

Now of course all programs are extensively commented in practice (well
nearly all :-) since they use meaningful variable names. If you see a
procedure called

  launch_rocket

you assume that it has something to do with launching a rocket. Indeed:

   procedure action_1096;
   -- procedure to launch_rocket

and

   procedure launch_rocket;

are pretty similar in terms of ones informal understanding of the program.
If in eiher case the routine actually causes (and is intended to cause)
the rocket to self-destruct, then you have an incorrect and misleading
comment in either case (and I would say a bug in either case).

P.S. Choosing effective names is an important tool for making programs
informally more readable, but I find it dangerous to rely on names alone,
they can often mislead at the detail level.