Re: kernel documentation is bad

Keith Rohrer (kwrohrer@uiuc.edu)
Mon, 21 Jul 1997 12:44:42 -0500

SirDibos wrote:
> The kernel is in a rapid state of flux. We should consider ourselves
> lucky to have whatever documentation we do have.
>
> Truth is, essential documention isnt in commented code.... its exchanged
> in email between the few knowledgeable developers and those who are
> becoming knowledgeable.
That doesn't mean that the "few knowlegeable developers" who find
themselves answering such questions (especially the same question
repeatedly) shouldn't put the answers into comments so (1) they don't
have to answer it again and again, and (2) people who want to know can
figure things out that much faster.

> If we forced documentation rules, this would kill kernel developement like
> nothing else. If you worry about docs, you arent going to bother molding
> and shifting the code.
Forced documentation rules are one thing. Not documenting a major
change which only you understand relies on everyone else being able to
figure out all the caveats and details from your code and change
everything *you* don't understand because they didn't comment it well
enough either.

> Most important: Do NOT solidify an interface. Once that happens, all
> fresh kernel developement will stop and it will merely degenerate into bug
> fixes.
Solidify, maybe not. Document, definitely! Specifying and documenting
an interface tends to get people to use the interface and use it as you
(-r docs say you) intended, so that when you do make changes to it,
everyone else's code was using the interface right, allowing you to
change their code without having to understand it (in most, if not all,
cases). With no documented interface, you can't change *any* part of
your code without hunting down *every* caller--including those which
call you by a function pointer--and figuring out how to change each
caller from scratch.

> Basically: When you are busy happily hacking away... You *cant* document
> all your changes, coz your hacks generally spread out over several time
> periods and stretches of code.
Either you are implementing a major change (like dcache), in which case
releasing half a change is much more useful if the rest of us understand
what's supposed to be going on (dozens of people searching for logic
errors and races are much more useful than hundreds of people seeing
what still crashes), or you're implementing a minor change which you
shouldn't be feeding Linus (or whoever) until you're done with it. If
your "hacks" are "spread out over several time periods and stretches of
code" to the extent that *you* don't know why you did it any more, how
are the rest of us supposed to know it? OTOH, concise "I changed this
because X" comments in patches fed to primary developers help them
understand what you did much more quickly (so they can do more "real"
work or accept more patches) and not only understand your change (so
they're less likely to forget and assume the "old" code) but see logic
bugs in it (esp. from misunderstandings of the original code)...

> What we have now is sufficient: Someone produces a patch that
> accomplishes a goal, with a short description of what it does. You should
> figure out from the patch how it alters the "base" kernel.
So where do we start? Is 0.93 far enough back? Yes, patches should be
reasonably documented, but so should the base code so that the patchers
truly know what they're doing instead of leaving bugs lying around for
third parties to find with mostly-unrelated code...

> I really suggest that a lot of you that have contributed to this whole
> "documentation" thread should read the FAQ for this mailing list. It
> should be posted shortly. When you see it posted within the next two
> weeks, *read* it. Then you'll understand why all this rigorous
> documentation would be more a hindrance than a help.
I don't support rigorous documentation requirements. I do encourage
appropriate levels of commenting, without which even one-man projects
become unmaintainable rather quickly. If the commented code isn't
understandable, the "open" software development is only really open to
those who have the time to figure out the whole shebang, and only the
developer who originally wrote a piece of code can catch subtle bugs
(which require full understanding to notice) and only then when those
bugs don't rely on subtle details of someone else's code which he
doesn't understand. Does Linus understand all the ins and outs of every
proprietary CD-ROM driver? Probably not, and he shouldn't have to.
Should all the writers of drivers for proprietary hardware understand
what Linus wrote well enough to use it properly? Hell yes.

I've found modularity to be essential even a small (~ 3000 line)
project, which wasn't changed very radically, just grown. If Linux is
to be extensible and mutable, good modularity is that much more
important, not only from a maintenance standpoint (to make a change, you
have to change less of the changed code's users) but from the standpoint
of how much of the code you have to understand (and therefore how much
documentation has to be good) in order to be capable of competently and
correctly extending or modifying the code.

Keith

-- 
The wisdom of G'Kar:
Bad Guys make a very satisfying THUMP when they hit the
ground.  But to thump the book of G'Quan is disrespectful.