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

Text File | 1992-12-14 | 3.1 KB | 85 lines

Newsgroups: comp.software-eng
Path: sparky!uunet!think.com!sdd.hp.com!zaphod.mps.ohio-state.edu!menudo.uh.edu!sugar!claird
From: [e-mail] (Cameron Laird)
Subject: Commenting style (was: C code Layout)
Organization: NeoSoft Communications Services -- [phone]
Date: Mon, 14 Dec 1992 14:03:10 GMT
Message-ID: <[e-mail]>
References: <[e-mail]> <[e-mail]> <[e-mail]>
Lines: 74

In article <[e-mail]> [e-mail] (Dick Dunn) writes:
            .
            .
            .
>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.
I don't have anything to add to Mr. Dunn here,
'cept my ongoing admiration of those who seek
out reality.
            .
            .
            .
>...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!)
            .
            .
            .
>what Bryant is showing us here.  How about:
>    i++;        /* done with widget i; skip the one after it */
Nice illustration.

Small point:  I have a small bias toward grammatical,
completely punctuated sentences in standard English.
There's nothing wrong with Mr. Dunn's idiomatic cap-
sulization, but I generally incline toward something
that looks like

            /* We have finished widget i; skip the one after it. */
    i++;

purely on "multi-cultural" lines.  I know all the pro-
grammers from my home town could parse Mr. Dunn's
comment without hesitation; I also know that anything
we write today is almost certain to be read by non-
native speakers of English, and by English speakers
from places far removed from my idiolect.  It's good
paring one's words down to just the essentials; it's
also good to form those words in a syntax that is
unambiguous, particularly across the ethnic boundaries
that are a significant feature of our professional
landscape.
            .
            .
            .
--

Cameron Laird
[e-mail] ([e-mail])    [phone]
[e-mail] ([e-mail])      [phone]