Messages in this thread | | | Date | Mon, 21 Jul 1997 21:31:49 -0500 (EST) | From | "Mark H. Wood" <> | Subject | Re: Take A deep Breath - Kernel Documentation |
| |
On 21 Jul 1997, david parsons wrote:
> In article <linux.kernel.m0wq3ci-00002hC@brando>, > Kevin M. Bealer <kmb203@psu.edu> wrote: > >Dietmar Kling wrote: > >>> do you mean something like javadoc? you run the source thourough > >>> and it makes doumentation? > >> > >>No, i think it's not good to have the source full of comments (they _are_ useful, agreed!) , there sho > >>uld be some kind of outside documentation. > >> > >(clip) > > > >I would agree with this. Code comments should not contain large scale > >documentation for a number of reasons: > > > >1. If the coder or documenter wants to update their code, they cannot > > do so seperately, it would have to be coordinated a lot. Linus > > should not have to handle integrating all the documentation, he has > > enough to do with the code. > > > >2. Documentation will always be a little out of sync, anyone who > > experiments a lot with code knows you can't keep it up to date > > for each tweak. If it is in a seperate file, it can be kept > > coordinated and also versioning would be seperate. > > Both of these reasons are arguments for keeping the documentation > IN the code; If it's a separate file, the designer may forget that > it's even there (particularly on a group development effort like > Linux) and thus not update the code (the whole idea of having one > person write the code and another person document it is, well, an > unexpected refugee from the IBM mainframe world in the 1970s.)
Oooh, I'm having flashbacks. "Literate programming", a la Web. (The programming language, not the marketing phenomenon.) Time to go read all the old arguments again.
Seriously, a well-made program product (there goes that ancient IBM stuff again) ought to have necessary but terse comments in the code, at close range so to speak, *and* a Program Logic Manual setting forth a framework that will last across a number of versions without getting too detailed. I know, I know, go then and do it....
Mark H. Wood Speaking, as always, for himself MWOOD@INDYVAX.IUPUI.EDU Our nation suffers from too little leadership, and far too much management.
| |