I have seen several attempts to add in comments to code after the fact.
In two cases, less technical people tried to simply translate the code
into English and used a boilerplate for each function. In these cases,
there were two very bad results:
- Some of the comments were *dead wrong*, and they were wrong in ways
which only a very careful reading of the code could possibly reveal.
This resulted in bugs later on and was a major problem. It would
have been far better to have no comments than wrong comments.
- By using lots of boilerplate whether or not it was really relevant,
and by documenting procedures down to a very low level, the size
of the average source file *doubled*. It took much longer to find
things in the files due many-line comments between every procedure.
Another point is that Linus is quite busy, and I wouldn't want to see him
get too distracted reading through reams of potentially inaccurate comments
trying to weed out the errors.
So my suggestion is, that if you'd like to put better comments in the
code, do only a little at a time and be very thorough. This is not a job
for a beginner, and the comments to be added should be sparing (no
boilerplate!), just enough to explain the non-obvious parts to experienced
programmers who already understand the kernel at a more general level
(explaining the kernel to laymen would be *hopeless*).
This would be a very good project, IMO, and a major challenge. I agree it
would help find some bugs, too, as well as ideas for enhancements and
making future maintenance easier.
----David C. Niemi---niemidc@clark.net---703-904-3596---Reston, VA USA----
We have a long and rich history, but no future save what we dare to dream.