Uncommented code in LilyPond

[address@hidden]

On 3 sept. 2012, at 07:33, David Kastrup <address@hidden> wrote:

> Janek Warchoł <address@hidden> writes:
> 
>> Hi John,
>> 
>> i remember that you are investigating whether we could be using Gerrit
>> for Lily work.  I may've asked this question already, but i don't
>> remember whether there was a definitive answer: does gerrit have a web
>> interface that allows to create new commits using only a web browser?
>> I've skimmed over
>> http://qt-project.org/wiki/Gerrit-Introduction
>> but didn't find any answer.
>> 
>> The reason i'm so concerned about this is simple: it would enable
>> hordes of LilyPond users (;-)) to participate in Lily development.
>> The following situation happened to me several times: a user had a
>> problem, i've explained how to fix it (or simply sent a link to
>> appropriate section in manuals), and i asked "how could we improve the
>> manuals so that you had found this information easier/understood it
>> better?".  Unfortunately, the responses are usually too vague to be
>> turned to a patch on the spot, and i don't have time to think about
>> them myself (and it doesn't make sense to ask the user to install
>> Lilydev and learn how to make a patch just for this).  With a web
>> interface, this would become massively simpler.
>> Also, Graham's catchphrase "patches appreciated" would become much
>> more powerful :)
> 
> Frightening rather.  I don't spend enough time defending LilyPond
> against awful patches as it is.  An automated system should likely
> reject any patch not containing at least 25% of comment lines in code
> areas (would be nice if this was the case for every submission).  Our
> quality of code is terrible, and part of the reason is that submitters
> just can't be bothered being interested in producing maintainable code.
> Part of the reason is that the existing code base is not really a
> shining example.  There is a lot of code that works because of fine
> points and underlying designs that are not documented, and so this code
> is useless as a template for how to write code that does not explode
> around everyone's ears eventually.


As a frequent producer of uncommented code that pushes into a code base with 
uncommented code, I am more than willing to put comments.  However, I'll say 
that a lack of comments has never stopped me from understanding how something 
works in LilyPond.  It is a single threaded program, so if you are not getting 
a result you expect, it is easy with valgrind or gdb to find where things are 
being set and why.

I don't get what the underlying design is of which you speak - what of it is 
undocumented?  Rarely are tricky things like "set_property" used and when they 
are, it is usually clear how and why (for example, the set_property calls in 
Stem::set_stem_positions are used to set stem positions).

As I have relative little coding experience, I have no clue what is or isn't 
good commenting practice.  I would be fine putting a comment above 
Stem::calc_control_points saying "This function calculates the control points 
for a stem" but I think all the information you need is in the function name 
and in the function's logic.

What did take me time to learn is how everything fits together (what a callback 
is, where things are triggered when, what happens before what).  Some sorta 
automatically generated flow chart may help this - I'm sure there are tools for 
that.

I've read through libraries that put paragraphs of comments above single lines. 
 I spend so much time reading the prose that I can't focus on the logic.  If 
variable names were called x0f00___EE7 in LilyPond, I wouldn't be able to grock 
the logic, but I feel stuff is pretty clear.

> 
> It is also a timebomb for maintenance since changes might violate
> underlying assumptions.

The regtests catch this, no?

> 
> And that is just talking about code that actually works for good
> reasons.  Quite a bit of code works since it has been prodded into not
> failing under those circumstances that tend to be tested.

I agree about the faulty code thing but not about the prodded thing - I think 
once the right test case comes up one can almost always find what is failing 
and why.


> 
> It is easy to make it easier to meddle with LilyPond code.  The low
> number of contributors is not due to our toolchains.  It is because few
> people are comfortable poking around in the dark.  And for good reason.
> 

I agree that LilyPond is gargantuan, but I think the main impediment to 
understanding how things work is a global lack of documentation about how 
things fit together.  This could be put in the CG.  If we can decide that 
certain basic elements of LilyPond's design will be frozen, this is worth 
doing.  It's already been done for certain core features (pure stuff, 
engravers).

I am completely on the same page with you about wanting to make LilyPond easier 
to contribute to.  Statements like "There is a lot of code that X" or "Quite a 
bit of code Y" may be true, but it is very tough to tackle the problem w/o 
concrete examples.  Could you maybe send out one or two case studies of what 
you mean?  I think it'd be instructive for everyone as a template for how to 
make the improvements you're talking about.

Cheers,
MS