Documentation {was Re: RFC change to process.c]

[linas at austin.ibm.com]

On Wed, May 28, 2003 at 01:53:18PM +1000, Paul Mackerras wrote:
>
> There is a good reason why thread.regs is NULL for a kernel thread -

Often when reading the source, I get the idea that there must be
a good reason for doing things in that particular way, but I can't
tell why, and there are no comments or other documentation
(that I know of) that provides guidance.

This concerns me. Yes, we can write to mailing lists like this,
but if you personally (and/or a handful of other people) are
on vacation, subtle changes that can induce subtle crashes can
subtley work into the source base.  In the long run, this hurts
reliability.

I don't know what the answer is, I just thought I'd bring it up.
I, for one, would like to see more in-line comments explaining
why code does certain things (not what it does, but why it does it).
Yes, I know that documentation is sometimes painfully misleading,
especially when the code changes but the comments don't ...
but overall I think its a win ...

--linas

** Sent via the linuxppc64-dev mail list. See http://lists.linuxppc.org/