On 3 sept. 2012, at 17:34, David Kastrup <d...@gnu.org> wrote:
> Janek Warchoł <janek.lilyp...@gmail.com> writes:
>
>> On Mon, Sep 3, 2012 at 1:00 PM, Graham Percival
>> <gra...@percival-music.ca> 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
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
