comments on comments

[Dave Jones]

There was some discussion about comments recently in comp.lang.c.

(Notice the followup-to line. Seems like the most appropriate
 group. Hope you agree. I'm not too familiar with the group,
 having just recently subscribed.)

I'm not a religious fanatic about it, but in maintaining lots of
different code since 1979, I have developed some preferences for what
I like in the code I am charged with maintaining, and what I could
do without.

Here are some remarks that I wrote up for one of the
members of my programming team.  I hope they will be
helpful.

....

In my opinion, the most important parts of a program to document
are the structure-declarations and the variable-declarations.
You document what the fields and variables "mean" in terms of
invariants.  Use descriptive names in addition to comments,
and don't use non-conventional abbreviations. If you do that, and
if the code is well structured, documenting an algorithm is usually
(but not always) unnecessary. Usually it is obvious how the algorithm
will go about the process of reestablishing a broken invariant.

Except in unusually tricky cases, the documentation for
a procedure should only say WHAT the procedure does, not
HOW it does it.  If the algorithm is not tricky, the WHAT
will make the HOW clear enough.   Comments which assert
the obvious are just clutter, worse than nothing.

Before you put comments into a procedure, ask yourself whether
there is some way to make the procedure itself understandable,
on its own. Perhaps you can give some variables more descriptive
names. Or you might even change the control flow. You may be
happily surprised to find that the clearer algorithm is actually
better!

A good way to sum this up would be to say, document things
which would be difficult or impossible for the maintainer
to surmise. If something is easy to figure out, don't
bother the reader with a comment. If something is hard to
figure out, ask yourself whether the complexity is necessary.

A comment which is inaccurate is worse than no comment.
Thus, comments should be "robust".  They should either
say things that are likely to remain true over the
lifetime of the code, or they should be positioned so
that it will be obvious to the maintainer when he
invalidates a comment.

For this reason, comments should only refer to their immediate
surroundings. If a comment says, "The previous four routines do
so and so...," a code-maintainer is likely to move one of the 
routines, or alter one without even knowing that he is "breaking" 
a comment. The same is true if a comment says, "This routine is
called by procA, and procB."  The maintainer of procA or
procB may not even know about the comment.  There are
utility programs for generating such cross-reference
information directly from the sources, without trusting
in comments.

Documentation about more general relationships between procedures
belongs in a separate design document, or in interface (#include)
files. Remember, it is the data-invariants which give
purpose to the procedures. Describe the data-invariants where
the data structures and variables are declared, typically
in #include-files.

If you want to make comments to yourself while you are
developing or maintaining the code, that's fine.  Things like,
"When this is integrated, routine foo() will call this routine...",
or "I think this probably does so and so."

But comments such as these should be marked somehow so
that they will be easy to remove later. I have found such
comments in code fourteen years old!   You don't want
to leave them there, so make it easy to remove them later.
I usually tag them with my login-name, which I certainly
DON'T want to leave in the code!

Block comments which are neatly delimited on the right margin
may look pretty, but they are hard to modify:

/************************/
/* This looks tidy, but */
/* it is hard to main-  */
/* tain.                */
/************************/

There's another problem with the comment above: It's not
one comment; it's several.  Utilities which look for comments
with certain keywords, etc. will not treat the above as one
comment.

Here's a good way to go about it:

/*******************************
 * This is one block comment,
 * and it is easy to modify.
 ******************************/