Some positives about documentation:
1. it encourages good coding style, especially if the docs are
co-located
with the code (inline documentation)
2. it makes it easier for others to read your code, modify it, expand
on it
3. it helps you to tell what the block of code is **supposed** to do
4. it makes it easier for someone else to maintain your code
5. it helps you understand code you wrote 1 year or more ago
6. it helps others to use interfaces you have designed, even if they
don't need to read or modify the underlying code
7. it is required for many projects and for many customers such as
those
for large banks, commercial entities, or DOD.
>
> Some problems with documentation:
>
> - is a poor substitute for code
> - can never be complete, accurate, or timely enough to match the source
> - <language> is much more ambiguous than C
They should compliment each other. Co-locating the docs with the code,
and encouraging updates of the docs when updating the code is a GOOD
idea.
For those wishing to learn an interface or about he code, docs are VERY
valuable. Keeping the docs and code in sync is simply good programming
practice. I have been using the SAME module header for 15 years and the
same header for procedures for nearly 10 years. They meet the needs
of my management and of all my customers.
> - encourages bad habits
> - developers substitute docs for readable code
> - people read the documentation and fear the code
> - when people do read the code, they interpret it as suggested by the
> documentation, missing subtle and not so subtle bugs
> - fewer people understand the actual code
Lack of docs encourages even worse code. Have you tried maintaining
code
you wrote 5, 10, or even 15 years ago. I have some C apps that I wrote
over 15 years ago that I ported to Linux -- the only way was to follow
the documentation and cookie crumbs (this procedure does A, B, C...).
One of the funniest stories about code and documentation was an EE 1
year
out of school who wrote a couple of hundred lines of 6809 assembler
without the first comment. He said it would work right the first time.
When he tried assembling it, it had over 300 errors! It took him weeks
to get it to work.
> - adds more inertia to the interfaces of a system
> - means changes require a greater investment of effort
> - implicitly promises things won't get changed
> - broken designs stay broken longer
Mainly adds a bit more typing and encourages a bit more work. Many
programmers **hate** the extra effort that it takes to properly document
their work, but that little bit of extra effort saves MUCH effort on
the part of others that are trying to understand that work, use that
work,
or expand upon it. It also help you to make sure that your code
really does what you want it to do....
Some have described code like an iceberg. The iceberg has 1/3-1/4 above
water and the rest below. The 1/3-1/4 is the effort to write/debug the
initial version. The 2/3-3/4 is the effort required to maintain that
code.
> - is a lot of work
> - and we've been doing pretty damn well without it
> - and there are good reasons to think it's a hindrance
> - and there are more important/interesting things to do
> - and you don't get very far telling volunteers to do things they don't
> want to
> - and other people who are motivated in that direction can do it
See last response....
>
> I think the informal commentary style of things like
> Documentation/exceptions.txt is far preferable to any sort of formal
> function-by-function docs, inline or otherwise.
For interfaces that are expected to remain fairly stable, in-line docs
that could be extracted into printable docs plus man pages would greatly
facilitate applications programming using those interfaces.
Cheers,
-- W. Wade, Hampton <whampton@staffnet.com>- 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/