On Wed, 26 Jul 1995 dlinder@Inacom.com wrote:
> In a previous letter, Russ Nelson wrote:
> > Read the code. Write down your understanding of it as comments.
> > Submit them as patches. If they're horribly wrong, someone else will
> > submit comment-bug-fixes. The only way to accomplish anything is to
> > do it yourself, not to exhort and cajole others.
>
> Then "cloister bell <cloister@hhhh.org>" wrote:
> >i have to disagree with that. comments in the code should *not* be
> >wrong; certainly not horribly so. if the point of having comments is to
> >help people understand the kernel, then adding incorrect comments can
> >only hurt that effort.
>
> I believe that Russ was implying that someone with a "more than minimal"
> knowledge of the sections of code they were commenting would be submitting
> the comments. I don't think that commenting should be the *complete*
> domain
> of the programmer working on the code.
I agree with this point. While I feel that the authors should have documented
in the first place (and made enough docs to reproduce the entire project),
that didn't happen with linux, and almost every other freely available unix
as well as a good number of the proprietary ones. Further, the authors ought
to be involved.
> Later, Cloister said: "[...] but i wouldn't submit kernel comment
> patches unless you have good reasons for thinking they're correct. if
> there are issues you're unclear about, ask about them here before
> finalizing your patch. [...]"
>
> VERY TRUE! Since everyone getting this E-mail should have access
> to reply to comments, it would probably be a great place to start asking.
> If things get too long winded, we could always start another mailing list
> for kernel comments -- Kernel Komments? :)
This stuff could teach the kernel while at the same time getting the
comments. That would be good. The mailing list should be created in the
process of creating the centralized submittal team.
> At any rate, Russ has made
> very good comment: "Linus does a good job of weeding out the cruft."
This may be a very true comment, but it represents something I never do:
I never plan anything involving another without the other's prior
agreement. We don't want to presume upon Linus' time. We make him sort
out the cruft anyways with real code and now he has to sort out the
comments too? He might as well write them...
> I would propose having one/two central people for a comment organizer
> and then let them submit the comments to Linus.
That's moving too fast. I propose we agree on a comment style sheet first (or
maybe in parallel with setting up the comment organization), and I refer you
to the one in "The C Companion" by Allan Holub as a first cut.