Messages in this thread |  | | | Date | Sun, 4 Oct 1998 00:10:32 +0100 | | From | Jamie Lokier <> | | Subject | Re: [Wildly off-topic] Re: Linus is on a powertrip.. |
| |
On Sat, Oct 03, 1998 at 01:40:59AM +0200, Andrej Presern wrote: > Consider heavily commenting the code in the patch.
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/
|  |