[lkml]   [1997]   [Jul]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
SubjectRe: documenting the kernel
Alan Cox:

: Just pick a bit of code and contribute docs, either to the Linux KHG
: or to comments/document files for the source tree. I'm happy to start
: checking them in and Im sure Linus won't object too much

I hope you check them for correctness and conciseness.

The interesting comments are global.
With well-chosen identifiers and a clean programming style
local comments are often superfluous.
Heavily commented code is not very readable.
But an incorrect comment can make finding a bug much harder;
without the comment one just reads the code, and sees a bug;
with the comment it requires mental effort to disregard it
while reading the code.

[In other words, I would prefer seeing the documentation go into
the KHG, and have comments written by the people who also wrote
the code.]


 \ /
  Last update: 2005-03-22 13:39    [W:0.046 / U:0.988 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site