lkml.org 
[lkml]   [1999]   [Sep]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [Q]: Linux and real device drivers
    On 26 Sep 1999, Nat Lanza wrote:

    > 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/

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