Documentation is essential, and in good professional
fully QA'd production code, I would consider 50:50
text and code to be about the right mix.
In modern languages line by line coding is dead. The
old IBM card format comments down the left column
is long gone. I don't really believe in putting much
text in to break up the flow of the actual code. As
has been said, the code should be clearly written,
**and clearly formatted** to make it the final
arbiter of "what the code actually does".
I also agree that during the mad coding/modification
phase it is foolhardy to do more than annotate key
things to remember and a skeletal framework for later.
Best way to start is to write your short API description
first, then start filling in the code.
But by the time you are going from Alpha to Beta, the
docs should be pretty well in place.
The documentation serves another purpose entirely.
It should:
for the user of the function/object
* Give a nutshell of what the function does
* define the API (inputs, outputs, sideeffects)
for the maintainer of the code
* define what the code was *intended* to do
* why the code was done this way rather than
one of the other options
* what assumptions were implicit in the code
* what special knowledge is required or should
be referenced
* what part this code plays in the overall
design
And the docs should be neat and well formatted so
they are readable on the page. Poorly formatted
docs are hard to read, hard to maintain and look
unprofessional.
------------------------------------------------------
Use Linux: A computer Dale Amon, CEO/MD
is a terrible thing Village Networking Ltd
to waste. Belfast, Northern Ireland
------------------------------------------------------
-
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/