In my experience the kernel is documented where it needs to be. Like my own code, it doesn't meet some arbitrary "programming by the book" rule about how many comments there should be, but instead provides comments where it is expected that they would be helpful to subsequent maintainers. Every year when I was assisting in the undergraduate first programming class we had to first beat it into new students that they need to write comments explaining what's going on in their code, and then beat it into them that useless (e.g. i++; /* increment i */) explanations are worse than none at all. Good documentation is like a good alarm system - it doesn't tell you about the ordinary, the routine, which you are expected to already understand. Contrast AWS (a railway safety system which alerts and requires action for all aspects except proceed, meaning it becomes more of a routine annoyance than an actual safety aid) with ATP or TPWS (systems which do nothing until an apparently unsafe condition occurs). Every comment is taking up space, both on the screen and in the maintenance programmer's mind. A short function with one comment pointing at an unusual condition for a loop may as a result be easier to comprehend than a similar function with sixteen multi-line C++ style comments explaining mundane things you ought to be able to pick up at a glance from the surrounding code ("this is a loop counter") or know as domain knowledge for the system you're working on. For example, if you work on code related to SCSI or filesytems or otherwise connected with disks, you're expected to recognise that (bytes >> 9) converts from a byte count to a sector count, since sectors are 512 bytes. Thus each incidence of this expression is not expected to attract a comment even though it may initially seem inexplicable to someone who has never worked with disks. I've had to work on several parts of the Linux kernel (though I don't think any code I wrote is currently in a Linus git repo) and I found it all satisfactorily documented. Unlike Tanenbaum if I were grading this project I would give it at least an A minus. Maybe you're just too sensitive - do you have trouble eating good cheese? Are you revolted by the thought that game isn't freshly killed when its made into pies ? Not everything needs to look like pristine sample code in order to be maintainable.
Copyright © 2018, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds