From: martinc@hatteras.cs.unc.edu (Charles R. Martin)
Newsgroups: comp.software-eng
Subject: Re: C code Layout
Date: 12 Dec 92 20:50:25 GMT
	<1992Dec12.200619.29602@fcom.cc.utah.edu>
Organization: UNC Department of Computer Science
In-reply-to: bryant@ced.utah.edu's message of 12 Dec 92 20:06:19 GMT

In article <1992Dec12.200619.29602@fcom.cc.utah.edu> bryant@ced.utah.edu (Bryant Eastham,MEB 3116,581-5353) writes:


   In article 8582@seq.uncwil.edu, herbst@seq.uncwil.edu (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)/martinc@cs.unc.edu
     Dept. of Computer Science/CB #3175 UNC-CH/Chapel Hill, NC 27599-3175
	    3611 University Dr #13M/Durham, NC 27707/(919) 419 1754
     "Oh God, please help me be civil in tongue, pure in thought, and able
      to resist the temptation to laugh uncontrollably.  Amen." -- Rob T
Newsgroups: comp.software-eng