Date: Thu, 11 May 2000 17:12:32 -0500
From: Ed Carp <erc@pobox.com>
Commercial code typically has comments in it to the effect of "this
block of code fixes bug #13456782", at least, and often has a short
description of just what "bug #13456782" was. Why is there so much
pressure to get a driver or a bug fix out the door that 5 minutes
can't be spent to do even the simplest of comments? Ted, I'm
surprised at you - you've been around long enough to know that
meaningful comments are more than helpful. Why the negative comments
about something that your experience tells you can be of use?
Because the complainer was complaining about something that's fairly
well documented already (IMHO), and adding more comments has the danger
of erring in the "/* add one to shutdown */" or "/* turn off interrupts
*/" stage. If someone sends me a patch of that form for the serial
driver, I'll reject it, and I didn't want someone to go through all that
work for nothing.
Whether there's enough comments or not or too many comments really is a
judgement call. I tend to prefer having things broken into functional
procedures whose names, plus a little comment at the beginning of each
procedure, is plenty. In some extreme cases you need to explain what
some tricky bit of coding is doing, but I don't believe in writing
programs that are meant to be read by someone who doesn't understand C,
or who isn't willing to spend at least a little bit of time trying to
bother to understand what's going on.
- Ted
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Mon May 15 2000 - 21:00:19 EST