lkml.org 
[lkml]   [1997]   [Jul]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: kernel documentation is bad
In article <linux-kernel@shoga.wwa.com> you wrote:
: The kernel is in a rapid state of flux. We should consider ourselves
: lucky to have whatever documentation we do have.

The best we seem to have now is user documentation, we have little
documentation on the design of the kernel.

: Truth is, essential documention isnt in commented code.... its exchanged
: in email between the few knowledgeable developers and those who are
: becoming knowledgeable.

That documentation, however, goes away, and is not in an easily updatable
format.

: 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' was the wrong word for me to use. I appologize to the people that
got all hyper about it. However, there may come a point in the future
where no one is capable of "molding and shifting" a piece of code because
no one can understand it.

: Most important: Do NOT solidify an interface. Once that happens, all
: fresh kernel developement will stop and it will merely degenerate into bug
: fixes.

Interfaces are what holds the kernel together. Now, there is a standard
interface for allocating memory, making a process block on I/O, etc.
These interfaces are, for the most part, solidified. Even when the
underlying algorthims and data structures change, none of the rest of
the code in the kernel will need to change. Now, if this already-defined
interface were documented, new developers (and others) would know
how to allocate memory (for instance) and have a relative degree of
certainty that their code won't need to change in the future when we
swith memory allocation schemes.

: 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.

With simple revision control, you can tell in an instant exactly which
lines in which files changed. With slightly stricter revision control,
developers are asked to enter a short description of the changes made
to each file. This would take a developer seconds to do, and would
improve our ability to track bugs.

: 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.

Why should we have to spend time figuring it out, when it would be ten times
easier for the developer to tell us what changed. (See below)

: 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.

The goal of documenting the kernel, its data structures, and algorithms,
is to SAVE time. Not necessarily the time of the 'current' developer,
but the time of future developers.

Come on you Software Engineering students, help me out here. If a
developer spent an extra 15 minutes documenting changes made to the code,
it could save future developers a half or maybe an entire hour. Since
your goal is to, as quickly as possible, add new features and fix old
bugs in the kernel, I don't see how skipping documentation helps anyone
in the long run.

\
 
 \ /
  Last update: 2005-03-22 13:39    [W:0.034 / U:0.104 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site