Messages in this thread | | | Date | Wed, 23 Jul 1997 12:41:54 -0200 (GMT+2) | From | Pieter Nagel <> | Subject | Re: Take A deep Breath - Kernel Documentation |
| |
On Tue, 22 Jul 1997, Darin Johnson wrote:
> Yeah, but is it maintainable if the developers go away? The problem > with your argument here is that it's a selfish one - the developer > himself may be productive, and if he's selfish, that's all he cares > about. The unselfish approach is to think about others who have to > deal with the code.
Concrete example: a year ago I wanted to get involved in kernel hacking, and I decided the best way to learn is start with something simple. The console driver seemed a horrible mess, I decided to pick it apart and clean it up as I go.
I came across two structs (vt_struct and something else, can't remember its name now) which seemed as if they actually should have been only one, they were always used in a 1:1 relationship.
Problem: were they split to facilitate some future enhancement to the interface, or were they not yet merged because the original developer never got round to it? Only the original developer would know.
A few one-line comments documenting the intention behind doing something some or other way would really have been good, in that situation. But I agree: the better the code, the less comments it needs. No need to write prose.
Source code documents algorithms; comments document intentions.
,_ /_) /| / / i e t e r / |/ a g e l
PGP: finger pnagel@epiuse.co.za
| |