lkml.org 
[lkml]   [1997]   [Jul]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    SubjectRe: Take a deep breath...
    Date
    And lo, Russell Coker - mailing lists account saith unto me:
    > >> Does anyone have any clue what makes any of us hack on this thing at
    > >> all? It's pretty simple, whats fun, interesting, and enjoyable to
    > >> work on, that is what we're going to hack on. Straight forward. I
    > >> happened to enjoy making a system solid, but not nearly as much as I
    > >> enjoy designing and implementing the latest and greatest.
    >
    > >Understood and agreed. From my own point of view, I'd love to contribute
    > >more to the kernel development efforts. Problem is, I can't read code
    > >like the Sunday newspaper. You and Linux, Alan, Eric, etc. seem to absorb
    > >overall design changes by osmosis. The mere mortals among us would be
    > >greatly inspired to pitch in by the presence of, umm, maybe just a wee bit
    > >more profuse documentation and commenting? I don't think I speak just for
    > >myself on this subject.
    >
    > So go and write some documentation then. There is a lot of useful
    > material that appears in this mailing list which is not adequately
    > categorised. If you could just sort it out, put it into web pages for the
    > KHG, or man pages or something then you would achieve what you want (a
    > better documented kernel). Complaining here will not gain you (or anyone
    > else) anything.
    >
    > Much of the documentation work doesn't require a really high IQ, just
    > time and persistance. Sure Linus, David, and Alan could spend more time
    > writing documentation, but that would mean less time writing code.
    > Why ask someone to spend their time doing something that you're capable
    > of doing yourself when they could be doing something you're not capable of?
    In "traditional" programming situations, I strongly hold to "*You* shall
    comment what you write, especially its interface." It's much easier for
    an author to write what he means by his code in natural language, while he
    still remembers what he was doing, than for that same programmer to go back
    and remember things later, or for a third party to have to figure things
    out from scratch.

    In cases where the code being added to the main kernel distribution is
    "stable" or "perfect and complete the first time", it's sort of okay to
    let documentation slide; after all, "it works", and people who need to
    figure it out will learn more by figuring it out than by having it told
    to them. Likewise, when the chief programmers are viewed as some sort of
    gods, you don't want them writing the documentation so people don't
    blindly believe the inevitable bugs in it.

    However, especially when Linus decides to throw a half-done (and likely
    otherwise buggy in ways nobody can debug until the change is "completed")
    but major revision into the code, I see great value in allowing the
    intelligent but non-telepathic masses in on the Great One's intent, so
    that we can have enough of an idea of what's meant to see bugs when we
    look at them, rather than not knowing what's a bug and trying in vain
    to justify how these bugs could be correct code. I remember some
    excellent descriptions of the big changes (losing verify_area and
    friends) around 2.1.2-2.1.4 written for developers-of-other-stuff...

    Additionally, I get the feeling that the major reason the current developers
    who can do things the rest of us are "not capable of" are that way (and are
    so few) partly because they both have the time to work on things and have
    already paid the learning curve and already know the existing code they plan
    on interfacing to or replacing. The step up from no documentation to minimal
    documentation almost certainly seems worth it: the first step in understanding
    new code is always the hard one.


    I admit, I haven't had time to contribute much of anything to Linux, and
    won't have time until my thesis is done, and as such I don't feel I have
    the right to say "you should do this". However, I do feel that code
    documentation, especially on substantially new code that nobody but the
    author understands yet, would be useful both for debugging and for adding
    to the base of competent debuggers and developers, and as such would be *a*
    good use of *somebody's* time. Those who don't agree will of course ignore
    me, and those who think they have better things to do (like me :-() will of
    course do those better things. And if I ever have difficulty understanding
    a piece of kernel and figure it out, I do promise to bounce a patchful of
    comments off of its author...

    Keith


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