On 1/10/2011 3:30 PM, Leo Butler wrote:
> < .... I suggest you sign them, in
> < the code.
>
> Please don't introduce needless graffiti into the source files like
> this.
I disagree with this. I think that browsing through the CVS is an
extra step, and that
when one is (for example) wondering why version n of Maxima does
something and version
n+1 does something else, finding comments in the code near the location
of the change, helps.
When code is anonymous (or anonymous until checking in CVS) it is too
easy to leave out
full explanations.
I also appreciate a line or two in the heading of a "share" file
identifying the author, date, etc.
Recently I came across a share file that was really in need of
revision, written in a very inefficient
and long-winded way. I eventually figured out that it was essentially
anonymously contributed,
part of the MIT 1982 legacy code.
> If someone wishes to know who did what and why, this information is available
> from the CVS log. This can be browsed from any decent editor, like emacs, or
> in a web browser from the sourceforge site.
Any decent editor, like emacs, can display comments in a form in which
they do not
intrude in the code (say in a different font and/or color), but are
easily available. Maybe
I'm old fashioned, but I find opening the CVS log at sourceforge to be a
pain. I'm not
objecting to using CVS additionally, to track changes, but
I do not see this a substitute for useful comments in the code, which I
believe should
reflect as much as possible, an explanation of what is intended by the
programs. And
I think as a courtesy to readers, an indication of the author.
In the case of a set of revisions widely dispersed, perhaps over several
files, in which a fuller
explanation of the >>changes<< can more reasonably be done in a CVS log,
in one place,
I think I would still prefer some comments that refer back to the CVS
log, in the code.
Perhaps in the header of the file, and also near where some large change
is made
in the source. Again, this would not be a substitute for comments in
the code
that might be added to explain what was going on (and, sometimes what might
have been going on before, that wasn't correct until changed.)
So I think we can do both --- but I hope the tradition of putting a name on
any substantial change (common in the MIT source code) is not lost nor
considered grafitti.
RJF