Re: documenting the kernel [and some praise :-)]
Andrew E. Mileski (aem@netcom.ca)
Thu, 17 Jul 1997 20:42:58 -0400 (EDT)
> > Although I do believe that well-documented code is useful, one should keep
> > in mind one danger with the approach suggested above: What happens if some
> > kind soul contributes documentation for a certain piece of the code, then a
> > developer comes along and changes the code? The documentation will no
> > longer match the code and in fact might become completely wrong. And *wrong*
> > documentation would IMHO be even worse than no documentation. So there
> > would have to be some way to insure that the documentation would either be
> > updated or remove when the code gets changed.
>
> Then that's a bug. If people care about that code, the bug will be
> reported and fixed. If no-one cares, its just like a driver no one
> uses.
If you change the code, you change the docs. A simple rule that [forgive
me, but its my opinion] only idiots break. It should be enforced too.
--
Andrew E. Mileski mailto:aem@netcom.ca