Messages in this thread | | | Date | Tue, 22 Jul 1997 11:17:15 -0400 | From | "Theodore Y. Ts'o" <> | Subject | Re: kernel documentation is bad |
| |
Randy, A lot of people have made some very sweeping statements about "the needs of the developers". What is best for any particular developer really depends on what sort of style they have. For example, I am very adept at reading and analyzing source code. It took me at most 15-20 minutes to figure out Linus's new dcache abstraction. I doubt the documentation would have speed up this learning curve by much; the interface was clean and didn't have many surprises, and I can read C just as quickly as I can read English. I am sure that it would have taken Linus more than 15-20 minutes to document the dache abstraction. Hence, your assertion that documentation always helps just simply isn't true --- all the time.
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
| |