NetNews Usenet Archive 1992 #26/NN_1992_26.iso/spool/comp/lang/c/16143

Text File | 1992-11-08 | 4.7 KB | 99 lines

Newsgroups: comp.lang.c
Path: sparky!uunet!mole-end!mat
From: [e-mail]
Subject: Re: Productivity of a C programmer ?
Message-ID: <[e-mail]>
Summary: Comments: not just the number but the purpose and the quality
Organization: :
References: <[e-mail]> <[e-mail]> <[e-mail]>
Date: Sat, 7 Nov 1992 02:16:05 GMT
Lines: 87

In article <[e-mail]>, [e-mail] (Richard M. Hartman) writes:

> Code/comment ratio shows how well documented the code is.  A low
> ratio you may have been spending more time explaining what you were
> doing than doing it.  A high ratio may mean that it would be hard
> for someone else to jump in and do maintenance.

> Each of these values were based on my whim of what I thought might
> be useful.  No flames on "that one is useless" please.  However, I
> am certainly open to suggestions about other metrics to add to the
> summary.        :)

Here's something to consider when counting comments.  I don't believe
that it can be automated, but when counting comment density, there are
three or four kinds of things to be explained by comments:

    1) The role that the code unit plays in the surrounding system
       (``... is used for all file operations'' ``totals the
       statistics requested by the -s flag'')

    2) Extraordinary interfaces or requirements imposed by the
       surrounding system.  (``The X3 total in the main tables
       can only be trusted _before_ we run the totalizers for the
       other categories'')

        3) Recondite or extremely theoretical algorithms.  (``This
       computes a discrete convolution using a linear-time
       algorithm; for the former, see Hirsh's *Mathematics of XYZ*,
       Chapter 6; for the latter, see JACM ... .  The basic idea
       is that ...'')

    4) Code that can't explain itself.  (``I1 is used as ... and as ...
       and as ... .  I2 is used as ... and ... and ... [followed by
       an ASCII-graphics flowchart].)

Comments in category 1 are probably neutral in a naieve comment-to-code
ratio; they are generally good but they can become outdated and can be
written in ways that increase the likelyhood that they will become outdated.

Comments category 2 probably count against the rest of the system.

Comments in category 3 probably count in favor of the code.  Whether
the algorithms are justified or not, of course, depends upon whether
there are simpler ways that are otherwise as good--and whether the
algorithms can be gotten out of a good library somewhere.

Comments in category 4 count against the code, plain and simple.

Comments that are written poorly should probably count against the code no
matter where they are.  Composition of prose is one of the hardest things
to do well; like virtue, it has no single standard of ``good enough.''

Sheer facility with language doesn't make one a good writer; for all Bruce
Catton's masterful use of American English idioms (``--on the Island Vale
of Avalon, at a guess--'',  ``Here was the man who looked as if he was
ready to drive his head through a brick wall, and since nothing else had
worked, perhaps that was the thing to try.''), it couldn't make his books
great.  His diligent research, like his `technique' with English, would
be useless if he couldn't organize his material.

Organizing the material is probably the hardest part of composition--and
the key to both good prose and good code.  It's also the hardest thing to
enforce organizationally.  Try suggesting, in a code review, that a comment
isn't clear enough.  Do it more than once or twice in a score of pages and
you'll be the project's pet crank.

This is a good exercise in criticism, by the way; if you _do_ succeed in
convincing people that a comment doesn't quite say what it should, you
may win points, but every criticism you make carries a cost.  Keeping the
total positive is wonderful discipline.  It also teaches you to zero in
on the essentials of an error or uncertainty: if you can ask ``is that the
elapsed time _before_ adjustment?'' and see half the people in the room
nodding as the importance of the question transpires, you've won a point,
but the same question asked in three or four sentences may cost you five
times the points you could have won.

Sheer quantity of prose, like sheer quantity of code, like sheer quantity
of ideas, is a very poor measure.  The editorial page of any newspaper has
plenty of ideas, but together they do not equal one of the penetrating
insights of an Aristotle or a von Clausewitz.  The mental chaos of a fugue
state has plenty of ideas but little value because they are neither properly
connected nor effectively directed.  So with code and so with prose.
--
 (This man's opinions are his own.)
 From mole-end                Mark Terribile

 [e-mail], Somewhere in Matawan, NJ