A certain amount of documentation is good, sure. And I try to
make sure that the general interfaces that I write do have
documentation. However, much, much more important that documentation
is a clean design. If the design is clean, then the code is effectively
self-documenting to someone who knows what they are doing.
I fault the "Software Engineering" college courses that are so
popular these days precisely because they make people overly dependent
on documentation. In the real world, documentation is rarely 100% up to
date. Hence, being able to read source code is essential.
Unfortunately, I have seen far, far, far too many programmers who (a)
are completely, 100% helpless without formal documentation, and (b)
couldn't design a clean abstraction to save their life.
I actually believe the two are related --- see my previous
posting about "thinking at multiple levels of abstraction", and how you
need to be able to do that in order to read and understand code.
Finally, if you want to pursuade kernel developers to better
document the kernel, I suggest you try an approach of thanking them and
encouraging those who do document their code and their interfaces,
instead of shaking your figures at them and complaining about how they
aren't following good software engineering practice. After all, those
developers have created a wildly successful OS from nothing; you might
want to give them credit for having *some* skills.
- Ted