comments on comments 
Author Message
 comments on comments

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 four{*filter*} 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.
 ******************************/



Mon, 20 Jul 1992 02:38:00 GMT  
 comments on comments

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

Thanks, I agree good documentation is invaluable.

Quote:

>In my opinion, the most important parts of a program to document
>are the structure-declarations and the variable-declarations.

This is true, but alternate design strategies can call for an
extended perspective on documentation.  When using an object
oriented design strategy, I'll first write a design document
describing the primary objects in the system and their operations.
Also in the document will be a high-level description of the
important procedures written in an informal PDL, such as a pseudo
Ada code.  For objects (Adts), first is a description of the object and
its rational and system context.  For instance, what the object is
intended for, why I chose an abstract data object or an abstract data
type, and possibly how it will interact in the system, but
the last part could go in a separate document as pointed out
by Dave Jones.  Second is a numbered list of operations and their
descriptions.   When the entire system is complete, the declarations
can be coded in a higher-order language.  In Ada, the design is directly
implementable as compilable specifications.  In Modula or some other
language in which the specifications aren't compilable the procedures
can be filled in with stubs or empty declarations.  The design document
can be included as comments and updates to the document and code should
be done concurrently.  The object descriptions are included in the
specifications and optionally in the package or module body, and the
(numbered) operation descriptions included for each procedure or method.

Quote:
>Here's a good way to go about it:

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

Here's another way:

/*
 * my_procedure
 *
 *    <ADT design document index>
 *    This is a description of...
 *    ...
 */

             Bob Hathaway



Mon, 20 Jul 1992 21:16:00 GMT  
 
 [ 2 post ] 

 Relevant Pages 

1. meta-comments for comments on proposals

2. comments on comments

3. comments on comments

4. Counting commented lines (full-line comments only)

5. Single Pound # comments versus Double Pound ## comments

6. How does your language grow? (Follow-up on comments on ADM Tuttle comments)

7. convert ! comments to standard comments?

8. Class comments

9. smalltalk parser and comments

10. - Your comments wanted!

11. Comment on APL and parallel hardware

12. apl2ital for TeX additional comments

 

 
Powered by phpBB® Forum Software