NetNews Usenet Archive 1992 #30/NN_1992_30.iso/spool/comp/software/4907

Internet Message Format | 1992-12-12 | 3.7 KB

Path: sparky!uunet!elroy.jpl.nasa.gov!swrinde!gatech!concert!borg!news_server!martinc
From: [e-mail] (Charles R. Martin)
Newsgroups: comp.software-eng
Subject: Re: C code Layout
Message-ID: <[e-mail]>
Date: 12 Dec 92 20:50:25 GMT
References: <[e-mail]>
    <[e-mail]>
Sender: [e-mail]
Organization: UNC Department of Computer Science
Lines: 65
In-reply-to: [e-mail]'s message of 12 Dec 92 20:06:19 GMT

In article <[e-mail]> [e-mail] (Bryant Eastham,MEB 3116,581-5353) writes:


   In article [e-mail], [e-mail] (R.T. Herbst) writes:
   >While directing the eforts of 125 people in producing the
   >A Data switching system for the Bell System- Good ol'
   >Ma bell-- I asked for a sample of code. I founr the comments to
   >be utter nonsense,. If one removed the code, the comments made no sense.
   >It was better to let the code speak for itself. If fact the code
   >was hidden in by the comments. Certainly we need well commented code.
   >Too many comments that try to say what the code is saying are IMHO
   >distracting.

Useless verbiage is useless verbiage, no question.  Comments need to be
directed toward producing insight in the code, not to meeting a
percentage standard or some such.  So to this extent, Herbst and I can
agree.

On The Other Hand -- I don't see how reducing the number of comments to
the block comment at top sort of standard can solve this: if the
comments there are misleading, verbose, or wrong you're in just as much
trouble.  The points seem to be orthogonal -- no number of BAD comments
help clarity.  On the other hand, too few good comments don't help
clarity much.

Now, then, as Brian says --

   Anyone can get lucky a couple of times. ;-)

   If you believe that K&R is "about right", then we will never
   come to agreement on what the right amount of comments is.

Trying to use K&R as a standard for code commenting is a bad mistake,
flawed by the assumption that the code in K&R in any way stands alone.
Examination of the text itself shows that the code does *not* stand
alone; for example, the description of basic I/O in K&R
first edition pp 159ff, contains about 7 1/2 pages of (poorly) commented
C code -- and about 10 pages of detailed prose description of what the
code does and how.  Total commentary about 1 1/3 lines of commentary to
1 line of code.


    [explanatory commenting....]
   can be a lifesaver for some poor person trying to maintain the
   code at a later time. The fact is that the second comment is
   MUCH larger and could even "hide the code", but there is no
   way that I will stop putting such comments in my code. I care
   too much for those who will follow me.

Long and long ago -- so long ago that there is some debate about whether
the managers were cold or warm blooded -- I had my first professional
programming job, in RPG II.  Not known as a clear language, but I was
(*cough*) quite good at it.  I wrote a couple of really nifty modules
that worked wonderfully, in a payroll system.  Now, payroll systems are
notorious for changing a lot, because the Gvt can't seem to settle on
the rules.  About six months after I wrote these nifty modules, I had to
change them.  I didn't have *any* idea what they did any longer.  I
pretty well had to throw them out and rewrite.  From then on, I
commented heavily.
--
        Charles R. Martin/(Charlie)/[e-mail]
     Dept. of Computer Science/CB #3175 UNC-CH/Chapel Hill, NC 27599-3175
        3611 University Dr #13M/Durham, NC 27707/[phone]
     "Oh God, please help me be civil in tongue, pure in thought, and able
      to resist the temptation to laugh uncontrollably.  Amen." -- Rob T