Messages in this thread | | | From | "Andrew E. Mileski" <> | Subject | Re: documenting the kernel [and some praise :-)] | Date | 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
| |