> 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.