Messages in this thread | | | Date | Wed, 29 Sep 1999 19:14:48 +0100 (BST) | From | Dale Amon <> | Subject | Re: [Q]: Linux and real device drivers |
| |
This is getting rather philosophical. But let me weigh in as someone who has managed design teams on reasonable sized software development projects.
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/
| |