Re: Uncommented code in LilyPond

[address@hidden]

On 4 sept. 2012, at 10:13, Rodolfo Zitellini <address@hidden> wrote:

>> 
>> 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.  It's my failing to
>> understand why they are useful.  If one gets the code by reading it, putting
>> comments (to me) seems dangerous in that it adds room for mistakes: people
>> can change the code but not the comment attached to it (I've been guilty of
>> this), at which point the comment is no longer applicable or, even worse,
>> false.  This can result in a huge loss of time.  And I'm not sure if there
>> would have been a gain of time in my reading these comments.  If I had read
>> them, I still would have gone down into the code and figured out what
>> various variables, functions, and loops did based on how they're used.
>> 
> 
> Hi Mike,
> One of the reasons I always had difficulty in contributing to LilyPond
> is that it's code is _really_ complex and _totally_ undocumented. I
> can read C++ quite well, and generally it is easy to understand what a
> function does. Eg.
> 
> int do_sum(int a, int b) {
> return a + b;
> }
> 
> It is easy to understand it just returns the sum of a and b. When
> someone else other than the coder (or even the coder after some time)
> will read this, he will wonder not WHAT it does, but WHY. Why did the
> original author write a function to sum a and b in the first place?
> 
> Comments are a fundamental way of describing the logic behind the
> code. Adding a comment like this to the above function
> /* Sums a and b */
> 
> is not useful at all, but this
> /* sums a and b, I wrote this unuseful function because I dislike
> pressing the "+" key */
> 
> is much more, it tells the reader your reasoning behind the code.
> 
> For a more Lilypond related example, I remembering struggling to
> figure out what was the logic behind all the scheme data structures.
> If I remember correctly, when you do \override of some property, lily
> pushes into the list the old value so you can \revert. All the logic
> behing this is totally undocumented. If you read the code, you easily
> understand that you are pushing properties around in lists. But why?
> in which order? the code itself does not tell you this. It took me a
> day of reverse engineering the scheme data using the debugger and
> Carl's help to figure out what was happening. A couple lines of
> comments describing what was the reasoning behind all this mess would
> have helped much and saved time.
> 
> So you do not need to put comments describing what every line of code
> does (unless you write really obfuscated c), but you should take some
> time to describe the reasoning behind wat you are doing. It will help
> the future maintainers, and yourself in some time - what seems clear
> and logic now may not in two years. It is not uncommon to scratch your
> head for hours trying to figure out what your own code does.

I think that's a great example you're giving above.  You're talking about the 
method behind an entire LilyPond practice (how overrides work internally) - 
this is very similar to "how pure properties work" or "how the page breaking 
algorithm works" or "how engravers work."  These are all covered in either the 
CG or the source via comments.

When I said that it'd be great for people to put /* TO COMMENT */, that is 
exactly the type of stuff I'd love to see in the code.  Feel free to propose a 
patch with a bunch of /* TO COMMENT */ - I think if we mark these things, it'll 
make it easier to not waste time writing useless comments like the one in your 
do_sum example.

I think you're absolutely right when you say "what seems clear and logic now 
may not in two years."  I don't have a good sense of what will and won't seem 
logical if I leave the project and come back in two years, so it'd help if 
other people indicate points in the code where comments should be left with a 
/* TO COMMENT */.  For example, in the accidental code that I just looked at 
which I never have read and is very old, comments seem like they'd get in the 
way - the logic is transparent and I'd be worried that comments add an extra 
level of maintenance (we now need to keep the comments in sync with the code 
logic).  If I came back and didn't understand the code in 2 years, I don't 
think it'd be because of the quality of that code specifically but rather 
because I forgot how LilyPond is internally organized.  However, I'm sure there 
are many places where the purpose of things is opaque.  This is where it'd be 
great if people put /* TO COMMENT */.  I think Graham would agree with me in 
saying that people can push this stuff directly to staging w/o review.

Cheers,
MS