On 1/11/11 2:03 PM, Mark H Weaver wrote:
> Robert Dodier <robert.dodier at gmail.com> writes:
>> On 1/10/11, Mark H Weaver <mhw at netris.org> wrote:
>>
>>> + ;; Modified by Mark H Weaver <mhw at netris.org> in January 2011 to add
>>> + ;; support for MCOND expressions containing more than one non-T
>>> + ;; condition, i.e. elseif, which was added after this code was
>>> + ;; originally written by RJF. The format of MCOND expressions is
>>> + ;; documented above the definition of dim-mcond in displa.lisp.
>> I'm sorry to say it, but this is a mess.
>> I'm all for comments in the code, but please, in the name
>> of all that is good, just stick to what's technically relevant.
>> Commentary like the stuff shown above is best left to
>> the CVS log.
> I agree with you, Robert. This comment was poorly conceived.
The issue of comments in the code has been discussed many times.
I, however, partly disagree with you and Robert. I think part of the
comment you gave *IS* relevant. I don't care too much about the name,
but surely the comment about supporting more than one non-T condition is
good. The reference to dim-mcond is good too. (Things in maxima are
spread all over and are often times not where I expect them to be. Grep
is my friend.)
If you were just given the code for new tex-mcond, would you be able to
figure out what it does? I would not be able to. But Mark's comment
about supporting more than one non-T condition helps a lot. I certainly
don't want to have to go to CVS to find the commit log for this,
especially after many commits have been done on this file. cvs annotate
can help, but given that people often times reindent things just because
they can, cvs annotate doesn't always help either.
I think we can all agree, however, that everyone should use good
judgment. If it was hard to figure out, by all means, put as many
comments as needed to describe it. (Be as brief as possible, but no
briefer!) If you needed some history to figure it out, then that might
be relevant. Or if the data structures are described somewhere else
that's not obvious, a cross-reference would be welcome.
Ray