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


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

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

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


                 Sponsored by the USENIX Association

                 David Tilbrook, Barry Shein, Chairs

When:   April 3 & 4 1989
Where:  The New Orleans Hilton, Riverside & Towers Hotel (504-561-0500)
        New Orleans, LA (call for reservations now!)



                            FINAL PROGRAM

Monday  April 3rd

9:00-10:30      Introduction and Keynote Address        Chair: David Tilbrook

                Vic Stenning
                "Project Hygiene"

10:30-11:00     BREAK

11:00-12:30     Version Management I                    Chair: Deborah Scherrer

                Steven R. Bourne, Sun Microsystems
                "What a Source Code Control System Should Do"

                Masahiro Honda and Terence Miller, Sun Microsystems
                "Software Management using a CASE Environment"

                Andy Glew, Motorola MCD
                "Boxes, Links, and Parallel Trees"

12:30-2:00      LUNCH

2:00-3:30       Version Management II                   Chair: Kirk McKusick

                Peter Costantinidis, Jr. and Hamish Reid, Unisoft Corp.
                "The DV System of Source File Management"

                Dale Miller, Sterling IMD
                "Controlling Software for Multiple Projects"

                Mel Pleasant and Eliot Lear, Rutgers University
                "Transcending Administrative Domains by Automating
                System Management Tasks in a Large Heterogeneous

3:30-4:00       BREAK

4:00-5:30       Testing                                 Chair: Barry Shein

                Barton P. Miller, Lars Fredriksen and Bryan So
                Computer Sciences Dept, University of Wisconsin, Madison
                "An Empirical Study of the Reliability of Operating
                System Utilities"

                Evi Nemeth, University of Colorado, Boulder
                Panel Discussion

Tuesday April 4th

9:00-10:30      Installation & Configuration Management     Chair: David Tilbrook

                Russel Brand and D. Brent Chapman,
                Lawrence Livermore National Laboratories
                "RAPID: Remote Automated Patch Installation Data Base"

                Susan A. Dart and Peter Feiler
                Software Engineering Institute
                "Configuration Management of an Environment"

                Tan Bronson, Microvation
                "The CCSLAND Configuration Control System"

10:30-11:00     BREAK

11:00-12:30     Release Engineering                     Chair: Deborah Scherrer

                Kirk McKusick, CSRG, University of California, Berkeley
                "The Release Engineering of 4.3BSD" (?)

                Don Davis, MIT Project Athena
                "Project Athena's Release Engineering Tricks"

                Jim Fulton, X Consortium, MIT LCS
                "Configuration Management in the X Window System"

12:30-2:00      LUNCH

2:00-3:30       Miscellaneous Topics                    Chair: Kirk McKusick

                Paul R. Eggert, Unisys Corporation
                "Automating the Importation of Software"

                Andrew Hume, AT&T Bell Laboratories
                "The Use of a Time Machine to Control Software"

                Peter Nicklin, Hewlett-Packard
                "Experiences Using a Hypertext Framework to Manage Software"

3:30-4:00       BREAK

4:00-5:30       The Grand View                          Chair: Barry Shein

                David Tilbrook, Nixdorf Corp.
                "Under Ten Flags: Software Management on Many Different
                Unix Systems"

                Panel Discussion and Wrap-up

Mon, 17 Aug 1992 21:53:00 GMT  
 [ 3 post ] 

 Relevant Pages 

1. Need comments on commenting program

2. Change C++ comments to C-comments

3. Multi-Line Comments Nested in Single Line Comments

4. changing C++ comments // to C comments /*

5. changing C++ comments // to C comments /*

6. Converting C++ comments to C comments

7. Why strip comment (was: Want a way to strip comments ...)

8. How to comment out chunks of code with comments most conveniently?

9. How to comment out chunks of code with comments most conveniently?

10. How VS.NET generates code comment reports

11. comments with XML tags?

12. Comment Generation and Creation question


Powered by phpBB® Forum Software