Theodore Y. Ts'o (tytso@MIT.EDU) writes:
> 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.
And I agree with you - I certainly wouldn't want to see it start looking like
ASM, where every line of code is commented (or should be!). But I think there
should be enough comments in the code such that a reasonably intelligent coder
with a year or two of C under his belt can follow what's going on. I
understand that there's times where you simply can't put enough comments in
code so the the guy off the street can understand (for example, I'm working
on a driver for Linux running on a PPC platform that does ATM stuff, it's
intended for multi-megabit switching backplane operations, and there's no way
that you would understand the driver unless you understood a little bit of
how ATM works), and I certainly wouldn't expect Alan Cox to re-write "TCP/IP
Illustrated" in comments, but let's be reasonable.
Also, there's the commercialization of Linux to consider. At the rate that
new features are being added to the kernel (and why do they *have* to be added
so quickly, anyway?), it seems that this is one goal, to have Linux accepted
commercially. But in order to get widespread acceptance, you've got to have
support, and that means that there's going to be a *lot* more people looking
at the kernel. If companies can't get support, can't hire people who are going
to be able to hit the ground running on the kernel, they're just going to go
somewhere else, and I don't think that's what this community wants, or needs.
-- Ed Carp, N7EKG erc@pobox.com 940/367-2744 cell phone http://www.pobox.com/~erc- 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