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

Text File | 1992-12-15 | 4.6 KB | 99 lines

Newsgroups: comp.software-eng
Path: sparky!uunet!zaphod.mps.ohio-state.edu!uwm.edu!spool.mu.edu!yale.edu!ira.uka.de!slsvaat!josef!kanze
From: [e-mail] (James Kanze)
Subject: Re: C code Layout
In-Reply-To: [e-mail]'s message of Mon, 14 Dec 1992 07:44:11 GMT
Message-ID: <[e-mail]>
Sender: [e-mail]
Organization: SEL
References: <[e-mail]>
    <[e-mail]>
    <[e-mail]>
Date: 15 Dec 92 18:11:19
Lines: 84

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.

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

If my memory serves me right, Kernighan and Ritchie actually say in
their book that the commenting there is lighter than it should be in a
production program, so that the programs don't take up too much space
on the page.  This is a valid argument for example programs in books,
where the text already says more than you would ever put in comments,
but Kernighan and Ritchie themselves apparently didn't think that this
style was adequate for production code.

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

And of course, if the next line is the closing brace of the body of
the for-loop, the comment "done with widget i" is superfluous, so just
"skip the next one" should be adequate.

One thing I haven't seen in this thread, however, is the importance of
commenting *why* you think the code works.  In all but the simplest
loops, for example, it is essential to state the loop invariants at
the top of the loop.  If this is obvious from the code, so much the
better, but in most cases it won't be.

Again, if you leave out a test for some specific condition because you
are convinced that that condition can never occur, some comment as to
*why* you are convinced is in order.

And any time you use something other than the obvious solution, then
some comment as to why it wasn't used is in order.  Note that in this
case, you're actually commenting the code that *wasn't* written.

I never cease to be amazed at the amount of code I see without such
comments.  In some cases, I know personally that the programmer has
though these things out, but you wouldn't guess it from their
comments.

--
James Kanze                             email: [e-mail]
GABI Software, Sarl., 8 rue du Faisan, F-67000 Strasbourg, France
Conseils en informatique industrielle --
                   -- Beratung in industrieller Datenverarbeitung