Messages in this thread | | | From | Keith Rohrer <> | Subject | Re: Take a deep breath... | Date | Wed, 16 Jul 1997 19:59:54 -0500 (CDT) |
| |
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
| |