Re: Uncommented code in LilyPond

[address@hidden]

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

Janek Warchoł <address@hidden> writes:

On Mon, Sep 3, 2012 at 1:00 PM, Graham Percival
<address@hidden> wrote:

I think that any time that a LilyPond developer complains that
the code is too hard to understand, the patch should automatically
move to Patch-needs_work.  Automatically.
If there's a long discussion and there's overwhelming opinion from
other developers that the code is fine, then we could ignore the
dissenting developer.  But unless there's *overwhelming* opinion
that the patch is fine, I think that a single complaint of
readability should render the patch un-pushable.

+1.
Hmm, adopting this policy would make me the most feared reviewer in
the community :-P

Shrug.  It is life insurance with the code as benefiter.  Nobody wants
to pay the premium, but if you don't, it won't survive for long after
you lose life or just interest in it.

--
David Kastrup

Hey all,

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_

Or:

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

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.

Cheers,

MS