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

Text File | 1992-12-14 | 3.9 KB | 80 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]>
Organization: eklektix - Boulder, Colorado
References: <[e-mail]> <[e-mail]>
Date: Mon, 14 Dec 1992 08:44:05 GMT
Lines: 69

[e-mail] (Charles R. Martin) writes:
...
>If I read it aright, Herbst "likes a format that leaves the code free of
>clutter" and therefore prefers to limit in-code comments to only those
>few setting off the sections, plus some comments on the general meaning
>of the code.

I read it somewhat differently.  I understood him to be objecting to
comments-for-comments-sake.  I don't see any objection to comments
describing difficult points, unusual constructs, etc.--although I'm led to
a feeling that I have, that the way to fix obscure code is to remove the
obscurity, and that therefore commenting around it is an admission of
defeat.  Better to comment than to leave it obscure and unexplained, of
course!

>I frankly have always found it very difficult to believe that anyone who
>suggests such a style has any professional software engineering
>experience...

Let me try to help you believe it.

I think the first matter is to narrow in on what the real difference is
between your perspective and Herbst's.  You've obviously been burnt by code
with inadequate commenting, Herbst by overcommented code.

If it would help, I could run some statistics on code I'm working on right
now--it's written in a style that our group finds fairly comfortable, and
we've been able to move pretty quickly with it.  I could characterize
things like comment size distribution, density, etc.  (Hate to suggest
getting so close to reality in comp.software-eng, but what the hell...)

>...My experience has *always* been that, on examination, the
>people who discourage detailed comments in code have spent their entire
>professional career in academic settings, writing code in a small group,
>with relatively little maintenance of code by anyone other than the
>author, and in general with products of only a few thousand lines of
>code.

I've had quite a different experience.

I've run across a variety of commenting styles/levels: minimalist, flowery/
ornate (rococode:-), rigid/formal/structured, logorrheic (?sp?).  I find
code from academia more often leading to endless tedious descriptions of
what's going on--I don't know whether it comes from faculty who have grown
accustomed to explaining the painfully obvious to students who don't want
to learn, semester after semester, or from being in a setting with a lot of
leisure to write on and on.  You'll also get a lot of commentary from the
folks being paid by the line (either implicitly or explicitly) - because
hey, comments don't have to work!  Easy productivity!  Defense-contract
code...urk, much bad magic, abandon all hope...  But if you look to
successful commercial programming, and look where the problems are new and
difficult (not just endless repetition of the last AR/AP code, or the last
controller interface), you find comments focusing in on what's really
needed, eschewing anything not obviously useful.  This last one is where I
live, and I really see it a lot.

>In the more common engineering environment, in which code must be
>expected to have a lifespan of several generations of programmers,
>*much* more detailed code commenting is not just desirable, it is
>essential.

If the code I have to work with, day to day, were strewn with detailed
comments, I'd go nuts.  I also wouldn't be anywhere near as effective,
because I have to deal mostly with code I didn't write...I don't have
*time* to wade through detailed comments except in the few cases that
they really say something important.  Concise is nice.
--
Dick Dunn    [e-mail]   -or-   raven!rcd    Boulder, Colorado
    ...Straight, but not narrow.