From: martinc@hatteras.cs.unc.edu (Charles R. Martin)
Newsgroups: comp.software-eng
Subject: Re: C code Layout
Date: 14 Dec 92 16:55:42 GMT
	<1992Dec12.200619.29602@fcom.cc.utah.edu>
	<1992Dec14.074411@eklektix.com>
Organization: UNC Department of Computer Science
In-reply-to: rcd@raven.eklektix.com's message of 14 Dec 92 07:44:11 GMT

In article <1992Dec14.074411@eklektix.com> rcd@raven.eklektix.com (Dick Dunn) writes:


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

   .... the style of code and the amount/style of comments
   do not differ significantly from what you'd have found in the UNIX source
   10-15 years ago.  In other words, Ritchie and Kernighan...and Thompson and
   others...wrote and write C in a style not too different from what you see
   in K&R.

   Next, step back and look at where UNIX has gone.  That code has been read
   and understood by tens of thousands of people, and has been successfully
   modified over and over again for many years, often by people with almost no
   training or aptitude.  Like it or not, there is massive evidence that the
   style DOES work, IS understandable, and IS maintainable.  It's *not* the
   only workable style!  But it works.

Well, I appreciate your kind comments [that I've deleted] but I disagree
with you on this one.  First of all "maintainable" is not a boolean.
I've been doing low-level UNIX hacking for a long while now, often
working from the BSD and occassionally AT&T sources.  While I agree that
it is *possible* to maintain the system from the KR&T level of
commenting, it is not -- in my experience -- very economic.  I don't
necessarily maintain that something like

	/* copy str a to str b using pointer arithmetic */
	while( a++ = b++) 
	    ;

is the level of detail comments need, but on the other hand older
research UNIX systems are just chock full of things like
multiple-indirection- and-shift expressions, complicated nested ?:, and
the like that just cry out for explanatory comments.  In the original
KR&T environment, where it was three or four guys bootlegging a system,
this was all right.  In a university setting, where labor is cheap and
expertice is its own reward, it is survivable.  If someone needs to
spend a week understanding the source for "script", well, it only cost
you $250.  Things are very different when a week costs $2000.

   If you want to understand the value and effect of comments, and of various
   commenting styles, I submit that you had better start with the understand-
   ing that K&R style DOES work.  If you've got the idea stuck in your head
   that it can't possibly be any good, then you'd better start by trying to
   figure out why it works.  As I said, reality is trump.

Ah, but what is "reality"?  (What is Truth, he said, washing his hands.)
It is a fact that UNIX has been extended and maintained in the past
without what I consider a useful level of comments; it is also a fact
that every commercial version of UNIX I've seen has at least a factor of
five more comments that the old AT&T sources.

Now, another ongoing thread in this group is about "literate
programming"; there appears to be a developing body of experience that
suggests literate programming is at least as productive (and maybe
more), and results in higher quality code that appers to be reasonably
maintainable.   This appears to be a direct contradiction of the notions
that herbst et al have expressed.
--
		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