Recent Features
| |||||||||||||
Kernel Documentation FantasyKernel Documentation FantasyPosted Nov 26, 2003 22:05 UTC (Wed) by iabervon (subscriber, #722)In reply to: Kernel Documentation Fantasy by utoddl Parent article: Review: Linux Kernel Development
Two problems with literate programming: It's generally relatively easy to understand the bit of the code you're looking at, but hard to understand the overall implications of it in the context of the system as a whole. Where would the information be that tells you, for example, the lock ordering rules? It also tends towards digressions. I've read some of TeX, and it reads more like a book about the difficulty of writing working and portable Pascal than anything to do with TeX. E.g.: The bane of portability is the fact that different operating systems treat input and output quite differently, perhaps because computer scientists have not given sufficient attention to this problem. Absolutely true, but why am I reading about this in this particular place? Because Knuth had to deal with it there. While interesting, this doesn't actually advance my knowledge of TeX, however.
(Log in to post comments)
Kernel Documentation Fantasy Posted Nov 27, 2003 2:49 UTC (Thu) by utoddl (subscriber, #1232) [Link] Caveat: I've done very little literate programming -- a couple of toy projects that were one-offs just to see what it looked like. It was fun. It was also a lot of work up front. I'll therefore take your comments at face value and consider that there is a core truth there. But to your specific points: "Where would the information be that tells you, for example, the lock ordering rules?" Probably in a section or sub-section entitled Lock Ordering Rules, and indexed under "locks" and "rules" and probably a few other ways. Where is the discussion on lock ordering rules now? In some terse comments here and there in the kernel source? No, it's actually scattered about in several years of kerneldev mailing list archives. The hard-fought, well thrashed out issues are important to understand, but their subtle influence on some of the code will be easily lost on the next generation of kernel hackers who try to learn how Linux works by reading only the code and embedded comments, but without those discussions. Old mistakes will be made again and lost lessons relearned the hard way. About your example digression: Yes, it is wordy. But I think it also advances my knowledge of TeX for the very reasons you cite. It gets across the context that we're about to deal with portability issues that may not be obvious to someone only looking at the code and who's familiar with only one or a few OSs, and only sees a "Danger, Will Robinson" comment with lots of exclamation marks. :-) Besides, in my Documentation Fantasy, the prose are always perfect, succinct yet engaging, with just the right touch of humor, and they always correct themselves whenever patches are applied. And corbet always checks 'em over in his spare time just to be sure. Hey, as long as I'm dreaming...
Kernel Documentation Fantasy Posted Dec 2, 2003 4:59 UTC (Tue) by iabervon (subscriber, #722) [Link] Ah, but a section entitled Lock Ordering Rules, indexed under "locks" and"rules", doesn't need to be part of the kernel source. In fact, it probably would do better not to be interspersed with any code at all. It's certainly something that's worth documenting (although the Linux principal of lock ordering is, "if you have to document it, it's too complicated"). For that matter, the ideal kernel document would contain explanations of everything that isn't in the code, and why. What the bit of TeX actually told me was why people use C instead of Pascal in general (the Pascal standard omits most of the things necessary for making a large project manageable). Personally, I'd love to have a complete explanation of the kernel. But I don't think that literate programming actually forms a clear presentation of an explanation (nor does it help to clarify the code itself).
|
|||||||||||||