Subject: Re: Adding to KNF.
To: None <tech-kern@netbsd.org>
From: der Mouse <mouse@Rodents.Montreal.QC.CA>
List: tech-kern
Date: 06/15/2002 13:28:04
> I hate mandatory comment blocks before functions!

I hate mandatory just about anything.  As soon as you require any sort
of documentation, much of it tends to be of crappy quality.  Lots of
coders, unfortunately, can't write documentation to save themselves; if
you require them to try, you'll get bad doc.  (Fortunately, there are
others who _can_ do good doco....)

All the rules in the world won't get good doc out of someone who can't
(or won't) write good doc.  And a good documenter doesn't need the
rules, and in fact may be hampered by them....

> They tend to end up telling you stuff that can be figured out
> immediately - rather than stuff that is slightly obscure.

Yeah, comments like

	count ++;	/* increment count */

are of little to no value.

I've written one-line comments for whole-screen functions, and
conversely I've written multiple screenfuls of comment for ten-line
functions.  It's all a judgement call....

>> An example from IPFilter:
[...]
>> /* Parameters:  fin(I)       - pointer to packet information                */
>> /*              np(I)        - pointer to NAT rule                          */
>> /*              natsave(I)   - pointer to where to store NAT struct pointer */
>> /*              flags(I)     - flags describing the current packet          */
>> /*              direction(I) - direction of packet (in/out)                 */

I really don't like this sort of thing.  If a given parameter's usage
is simple, there's no need for this much goop; if it's complicated,
there isn't enough space here and you just have to write something like
"see below".

Okay, that's a bit of an exaggeration.  But I think there's some truth
in it.

/~\ The ASCII				der Mouse
\ / Ribbon Campaign
 X  Against HTML	       mouse@rodents.montreal.qc.ca
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B