I was hoping someone would mention exactly this point. I'm glad
I'm not alone with regards to what is and what is not "good" documentation.
>From a practical standpoint, programmers often have to maintain code written
by people who have since left the project/company. In cases where the author
is no longer available to answer questions, having documentation that explains
why certain decisions were made makes code maintenance much easier and safer.
If the routine is long or complex then perhaps even a brief outline of what
is supposed to happen is helpful.
There is nothing worse than receiving a bug report and narrowing the problem
down to a chunk of code whose only comment is "This next bit of code is messy
but it works."
> > - when people do read the code, they interpret it as suggested by the
> > documentation, missing subtle and not so subtle bugs
>
> Conversely, documentation can make a bug easier to find, because when
> comments say one thing and code does another, people start to wonder.
I would go a step further and say that good documentation can also alert
people to problems that the author may have encountered or foreseen
that affected the final design. Something like: "the obvious ways
of doing this are <stuff> or <stuff> but neither will always work
because of <reason>." Again, this gets back to documenting the "whys"
and not necessarily the "whats".
Jimmie
-- Jimmie Mayfield http://www.sackheads.org/mayfield email: mayfield+usenet@sackheads.org My mail provider does not welcome UCE -- http://www.sackheads.org/uce
- 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/