Re: Uncommented code in LilyPond

[Rodolfo Zitellini]

>
> 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.

My 2c :)
Rodolfo