Beware, _good_ comments are great but see
/usr/src/linux/Documentation/CodingStyle:
| Chapter 5: Commenting
|
| Comments are good, but there is also a danger of over-commenting. NEVER
| try to explain HOW your code works in a comment: it's much better to
| write the code so that the _working_ is obvious, and it's a waste of
| time to explain badly written code.
Over-commenting is a temptation to be especially resisted with small
patches. If every patch adds additional comments, a lot of cruft over
the ages will accumulate, and most of it will become obsolete without
being trimmed away -- it takes more work to trim old commentary than to
write new commentary.
On the other hand even the tiniest patches should include a comment if
they do something non-obvious, such as work around some obscure device
bug or have a subtle effect on the memory management heuristics. A good
rule is, if you can work it out from the code without too much effort,
it doesn't need a comment. If there's no way to work it out from the
code, a comment is essential.
I think the level of commenting now is quite reasonable, even if it is a
bit messy in places. The code for the core kernel is quite clearly
written even if there is a huge bag or tricks going on in there.
-- Jamie
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/