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

Text File | 1992-12-14 | 4.9 KB | 107 lines

Newsgroups: comp.software-eng
Path: sparky!uunet!zaphod.mps.ohio-state.edu!cs.utexas.edu!asuvax!ncar!csn!raven!rcd
From: [e-mail] (Dick Dunn)
Subject: Re: C code Layout
Message-ID: <[e-mail]>
Summary: theory and practice
Organization: eklektix - Boulder, Colorado
References: <[e-mail]> <[e-mail]>
Date: Mon, 14 Dec 1992 07:44:11 GMT
Lines: 95

[e-mail] writes:
>[e-mail] (R.T. Herbst) writes:
>>[stuff about large successful projects, emphasizing concise to-the-point
comments]

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

Well, ;-) or no, that's a bad attitude.  Reality is trump; get used to it.
It's hard to defeat something that works in practice with an argument only
demonstrated on paper (or phosphor:-).

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

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.

The style of code and the level of comment in K&R is influenced by the fact
that it's a language text, as Charlie Martin pointed out.  Realize that the
code examples in K&R are written to illustrate points, and are accompanied
by a lot of text to explain them to people who are just learning C.  Still,
keeping that in mind, 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.

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.

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

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!)

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.

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.

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

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.
--
Dick Dunn    [e-mail]   -or-   raven!rcd    Boulder, Colorado
    ...Straight, but not narrow.