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

Text File | 1992-12-14 | 5.1 KB | 128 lines

Newsgroups: comp.software-eng
Path: sparky!uunet!pmafire!news.dell.com!swrinde!cs.utexas.edu!sdd.hp.com!saimiri.primate.wisc.edu!zaphod.mps.ohio-state.edu!sol.ctr.columbia.edu!hamblin.math.byu.edu!news.byu.edu!ux1!fcom.cc.utah.edu!provo.ced.utah.edu!bryant
From: [e-mail] (Bryant Eastham,MEB 3116,581-5353)
Subject: Re: C code Layout
Message-ID: <[e-mail]>
Sender: [e-mail]
Reply-To: [e-mail]
Organization: Center for Engineering Design
References: <[e-mail]>
Date: Mon, 14 Dec 92 17:55:33 GMT
Lines: 115

In article [e-mail], [e-mail] (Dick Dunn) writes:

>If you don't understand why K&R is "about right", you need to stop and
>think about the real significance of it before doing any more pontificating
>about commenting code.  This is not an "Is Too!"-"Is Not!" matter; it is a
>theory-vs-practice matter.
>

Sorry if I made it appear that way (Is Too! - Is Not!).

>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.
>

I suppose that explains why the examples of poor (very poor) commenting
style for my senior lab class were from the source for UNIX! No lie,
one assignment was to comment the command "strings", which (from the
distribution) had (if I remember right) ONE COMMENT LINE. I don't know
who that style works for. Certainly not anyone in the class or the
instructors.

>Some of this is like trying to explain Thoreau to people who like gothic
>cathedrals, but I press on...
>

Some of us feel the same way.

>back to Bryant, who talks about the difference between useless comments,
>like:
>>   i = i + 1;   /* Increment i */
>(no argument here, of course)
>
>....and useful, necessary explanations like:
>
>>   /*
>>    *  We are now done with the code for widget i, and while
>>    *  the "for" loop will increment i again, we want to skip
>>    *  the next widget and so we increment i here as well.
>>    */
>>
>>   i = i + 1;
>
>The *idea* of commenting this situation is good.  You don't want somebody
>looking at it, wondering whether the increment is supposed to be there or
>was left over from a different sequence, etc...it's a good situation for
>stopping to describe what's going on.  It's the realization that is bad.
>(To a C programmer, the first problem is that the code should be
>    i++;
>You don't ignore the idioms of the language unless you're trying to confuse
>the people reading the code.  I thought we were trying to avoid that!)
>

i++ vs. i = i + 1? What was that about Gothic cathedrals??

>Next, you've got seven lines for a very simple task: one line of code, one
>blank line, two gratuitous ornaments, and three lines of loquacious
>description in which the real point ("skip the next widget") comes late in
>the sentence.
>

I agree. The example was not to be taken quite so literally, but believe
me I have code where a simple increment needs that much explanation. We
just finished our last project (this is my work now) at just over
75,000 lines of code. The people I work with are glad that I comment
the way I do. As you said, if it works...

>Realizing that we're taking code out of context, but I think I understand
>what Bryant is showing us here.  How about:
>    i++;        /* done with widget i; skip the one after it */
>The comment is still too wordy, but at least it doesn't take up 10% of
>the current on-screen space to describe a single integer increment.
>

Again, too wordy for one is not enough for another. The blank lines
and "gratuitous ornaments" are very much a matter of personal style
and if used consistantly are fine for me.

>In small programs, neither a dearth nor a surfeit of comments will do much
>damage.  But, of course, small programs aren't the hard ones.

Remember that "strings" assignment? The original source fit on one
page. Many students would argue the fact that small programs can be
the HARDEST ones!

>Once a
>program gets large, the very job of understanding enough of it to be able
>to work on it is a problem.  Then, anything that doesn't explicitly help
>definitely hurts.  Don't omit comments that could help explain what's going
>on...but don't put something in just 'cause you're feeling guilty that you
>haven't written a comment for ten lines.
>

Well said.

>It *is* undeniably hard to develop a sense of what's obvious (needing no
>explanation) and what isn't.  But it's part of learning to program well,
>and until you learn that, it's as easy to err on the side of too many
>comments as too few.

Again, I agree. Sorry to keep this going for so long. Matters of style
are too hard to articulate with a keyboard. That must be why we argue
about them so much.

>--
>Dick Dunn    [e-mail]   -or-   raven!rcd    Boulder, Colorado
>    ...Straight, but not narrow.

Bryant Eastham
[e-mail]