> Oliver Xymoron <oxymoron@waste.org> writes:
>
> > The basic level of knowledge stuff can already be bought at your book
> > store. Linux Kernel Internals, Linux Device Drivers, Design of The Unix
> > Operating System, etc.
>
> Books are static. The kernel is not. Given the current rate of kernel
> development, books on it are outdated almost as soon as they hit the
> shelves. What good is a basic introduction if it's outdated and
> therefore wrong?
The books (ahem) acknowledge that the only authoritative document is the
code itself.
> > Obviously, external interfaces (syscalls, ioctls, /proc) are a different
> > story. But what we're arguing about now is the internals. Or should the
> > whole underside of the kernel that modules talk to be declared an external
> > interface and written in stone? Next you'll want binary compatibility and
> > we'll be one short step away from having a microkernel.
>
> Even the internals can have some stability. If I'm writing a set of
> modules, which is a better way to spend my time -- chasing after
> changes to the kernel interface or making my code better?
Gratuitous changes occassionally occur, but usually things are changed for
the better. That debate is orthogonal to documentation.
But if you're going to go to the trouble of documenting all the internals
used by modules, you might as well call them externals. And prepare to
live with them for the next 20 years.
> > This is a straightforward consequence of the investment in documentation.
> > "Hey, I just wrote this nifty new subsystem and all these docs. Oh look,
> > there's a nifty way I could improve it by doing <foo> everywhere. But then
> > I'd have to change the docs. Hell with it."
>
> Laziness is laziness, and no system can prevent that. Currently we
> have "Oh, then I'd have to change everything in the kernel that uses
> <foo>". I'm not convinced that adding "and write a paragraph
> explaining it" is really a killer task compared to that. Even if the
> guy who made the change doesn't want to add that paragraph, someone
> else can. What's important is that it exists, not who wrote it.
If Linus doesn't require someone to document their changes, how is that
different from today? People are certainly welcome to contribute docs.
Saying that we _should_ have documentation implies that developers
_should_ do it themselves.
> > Umm, yes. Unreadable code is hard to maintain. Documented unreadable code
> > is not much better - you still have to read the code to fix it and maybe
> > just to use it. Systematically documenting everything with man pages,
> > etc., including the readable code (which a lot of the kernel is, happily),
> > is a step in the wrong direction. Effort is better spent on making the
> > code comprehensible.
>
> Why do you think I'm advocating documentation at the expense of
> readable code? Argue against my position if you like, but please stop
> constructing strawmen. Please show me where I or anyone else claimed
> that writing documentation was more important than cleaning up code.
It's implicit. Developer resources (either time or motivation) are finite.
Documentation effort therefore must take away from code effort. Code that
benefits from documentation is code that is unreadable. From
Documentation/CodingStyle:
Chapter 5: Commenting
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of
time to explain badly written code.
Most of the stuff in Documentation are for users rather than developers,
which is as it should be. The internal documentation for developers that
does exist contains the broad outlines only, which is as it should be.
-- "Love the dolphins," she advised him. "Write by W.A.S.T.E.."
- 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/