Re: some comments and complaints on the code (issue 5651069)

[David Kastrup]

Han-Wen Nienhuys <address@hidden> writes:

> On Sat, Feb 11, 2012 at 8:31 AM,  <address@hidden> wrote:
>
>> Well, the main point of the comment is not describing parameters, but
>> the function itself.  Believe me or not, we spent 10 minutes figuring
>> out _what the hell_ are apes doing here and whether there are any
>> bananas involved.  It's stupid, i know.  But there must exist a way
>> of writing code that is understandable for the newcomers after second
>> reading, not after 10 minutes.
>
> I disagree.  Reading code the first time is hard, that is true, but
> unless anything surprising is happening, it does not deserve a
> comment. The more you read code, the easier it becomes, and think of
> this as you learning how to read.  In an analog: beginners books may
> feature simpler words, hy-phe-na-te all words explicitly and use
> pictures, but that doesn't mean literature for grownups should have
> those.

The problem with much of the LilyPond code base is not that it is short
in comments paraphrasing the code: I agree that those are mostly a
distraction getting out of date.  The problem is that it is short in
comments reporting the _purpose_ of code.

I've just looked at the part combiner code, and it creates complex GOOPS
structures and meddles with them, and sorts things and stuff.  And even
though there are a few comments, those are just of the _paraphrasing_
kind.  They tell you what you could have figured out on your own.  They
don't tell you what is actually happening according to what plan and
design and where all of this is supposed to fit in why and how.

Architecture is not the same as masonry.

-- 
David Kastrup