Re: Uncommented code in LilyPond

[David Kastrup]

"address@hidden" <address@hidden> writes:

> I started doing commenting in accidental.cc and
> accidental-engraver.cc.
> I found myself in the pattern of:
>
> looking at a variable with a name (like a boolean called done_)
> going down into the code to find out what done_ means
> going back up to put a comment next to done_

> looking at a function
> reading what it does
> going above the function to write a resume of what it does
>
> What has been good about this exercise is that I've found a bit of
> cruft that can be deleted and a couple minor speed-ups possible.
>
> However, I still don't understand the utility of more comments in
> these two files after all of this. Note that I am not calling into
> question what David is saying about comments - I'm sure he is right.

Ok, here is the thing: the real importance of comments is to write down
what is _not_ written in the code.  It is not training wheels for code
readers, but teleportation.

Like I said: if you come into your yard and see someone building a wall,
and you ask him "what are you doing here?", you don't want to hear how
he is making his mortar, and how he is putting one brick on another, and
how he is making sure that the walls meet at right angles.

You want to know what his business is to be there in the first place.
Who sent him there.  Who paid him for that and why.

So the most important job of comments is to tell the story _behind_
code.  For accidentals, most of the "why" and "wherefrom" is obvious
(though cautionaries and other stuff might be trickier).  The
interactions with various other elements, slurs, beams, accidental rules
might be less obvious.  So it makes some sense to sketch this out at the
top of the file, including pointers to the files and originating events
that might also come into question for various kinds of accidentals
(accidentals in key signatures, accidentals in ambitus, cautionary
accidentals, musica ficta, trill accidentals and pitched trill
accidentals and so on).

Basically, if you are experiencing a problem with accidentals, a
reasonable expectation is to look at the accidental.cc file and get a
rough clue where to debug things.  If the code does not tell the story,
the comments should.

There are basically two kinds of comments: those that tell the story,
and those that tell local design.  The second kind of comment is the
stuff you can reconstruct by looking hard enough at the code.  They save
time and help to narrow down on what actually might be problematic right
now.

The first kind is what is really important.

If you have some file accidental-cross-stub-engraver.cc without any
comment in it and without any other file pointing to it, you have no
clue how this is supposed to fit into the scheme of things.  And that's
worse than having to track down the line-by-line logic of the file.

So yes, nice accompanying code comments are a good idea.  I think
note-collision.cc does a fine job explaining the patterns it deals with
using pictures of ASCII art: I don't like the code in its details, but
the per-code commenting is really what I would like to see elsewhere.

But the really important thing is: why is this code even there?  The
whole of it?  What music constructs will trigger it?

Having just one long block comment at the top of the file that justifies
the file itself and the circumstances when its entry points will get
used for what purposes would help _a_ _lot_.  Code reading help is fine,
but what we really need is the information _when_ and _why_ code will be
used.  The bulk of it, not just single lines.  The connection between
files of code, and functions, and music, not just the connections of
code lines inside of a function.

> Again, this is my failure to get which comments are useful and which
> aren't, so I'm not against the proposal to add more. What I need in
> order for my work to be efficient is for someone to go through and
> mark places in the code /* TOCOMMENT: - why is X doing why */ or what
> have you.

Again: the background story is what is important, not the words with
which it is being told.

-- 
David Kastrup