[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: collision beam with staff-crossing beam
From: |
address@hidden |
Subject: |
Re: collision beam with staff-crossing beam |
Date: |
Wed, 13 Feb 2013 15:25:44 +0100 |
On 13 févr. 2013, at 13:50, David Kastrup <address@hidden> wrote:
>> I would rather make a concerted effort where people decide on a style
>> for documenting our API (standardizing function names, documentation
>> style, etc.) and then we do it rather than doing a piecemeal job.
>
> Mike, you can either increase the ratio of undocumented functions and
> APIs whenever you add new ones, or you can decrease it. The latter is
> not all too hard, so it makes sense to go for it.
The most time I lost in LilyPond development in my first couple years was from
reading comments that for some reason were obsolete or non-indicative of what
was actually going on. Once I started just reading the logic of the code,
everything got much easier. So I am 100% pro telling the story but this needs
to be done in a coherent way. I realize that talking about user documentation
is a different issue, but I think it needs to benefit from the same coherence
and uniformity.
>
>> Someone needs to lead this.
>
> That's just an excuse for not documenting anything. I don't buy your
> premise that things need to get worse until some hero appears and
> actively makes them better.
This is not an excuse for not documenting anything. Every time I add a
property I document it because there is a structure in place w/ ample examples
of how to do so. Ditto for interfaces. Ditto for LY_DEFINE.
An API for LilyPond is a long talked about, excellent idea. Once someone who
is passionate about it comes up with rules about how it is done, like C++
indentation, I will follow it to the best of my abilities, exactly as I do for
properties and interfaces and LY_DEFINE.
>
>> Graham did this sort of thing for documentation a few years back and
>> it was an excellent idea. The discussion could be organized in the
>> same way as GOP and GLISS stuff.
>
> It is not a matter of "discussion". It is a manner of making it a
> principle to write down what one was thinking instead of just coding the
> outcome, whenever it is relevant to understanding code.
This is where I get the most help from reviews - I add comments when people ask
me what things do. It is not obvious to me when things are relevant and not.
Cheers,
MS
- Re: collision beam with staff-crossing beam, (continued)
- Re: collision beam with staff-crossing beam, Janek Warchoł, 2013/02/12
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13
- Re: collision beam with staff-crossing beam, address@hidden, 2013/02/13
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13
- Re: collision beam with staff-crossing beam, address@hidden, 2013/02/13
- Re: collision beam with staff-crossing beam, David Kastrup, 2013/02/13
- Re: collision beam with staff-crossing beam, address@hidden, 2013/02/13
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13
- Re: collision beam with staff-crossing beam, address@hidden, 2013/02/13
- Re: collision beam with staff-crossing beam, David Kastrup, 2013/02/13
- Re: collision beam with staff-crossing beam,
address@hidden <=
- Re: collision beam with staff-crossing beam, David Kastrup, 2013/02/13
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13
- Re: collision beam with staff-crossing beam, David Kastrup, 2013/02/13
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13
- Re: collision beam with staff-crossing beam, David Kastrup, 2013/02/13
- Re: collision beam with staff-crossing beam, Werner LEMBERG, 2013/02/13