Re: collision beam with staff-crossing beam

[David Kastrup]

"address@hidden" <address@hidden> writes:

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

Did you fix them?  If not, why not?  Bad or missing comments are _bugs_.
When the computer does not understand what he is supposed to be doing,
that is a bug, and when the fellow programmers do not understand what
they are supposed to be doing, that is a bug.  If a computer takes an
inordinate amount of time running code, that is a bug, and if a
programmer takes an inordinate amount of time reading code, that is a
bug.

If you do git log lily/include/smobs.hh, you'll notice that the last two
commits were _only_ comments.  Comments that put down understanding I
had to derive the hard way.  If you find information like that missing
and figure it out the hard way, _write_ _it_ _down_ so that the next
programmer has an easier job.

> Once I started just reading the logic of the code, everything got much
> easier.

So why do you choose function names that don't make sense, variable
names that don't make sense, and factor your code in a manner that does
not reflect the logic of the task you are solving but rather the steps
that occur as a consequence of the task?

The original code by Han-Wen and Jan is code by _experienced_
programmers.  Its lack of comments is a total nuisance, but the logic of
the code is somewhat transparent.  An excellent musician or dancer makes
hard pieces appear deceptively simple to perform, reflecting their story
rather than their notes.  An excellent programmer is able to let the
code reflect its design rather than just its operation.

The damage of Han-Wen's and Jan's original coding style is not just that
it makes it hard for others to work on the code.  It is also setting a
bad example, like an electrician soldering bulbs directly onto wires,
one that is likely to cause accidents when people have no comparison to
go by and get led to think that this is how things should be done.

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

Forget user documentation.  It is not relevant to why your code is
unmaintainable.

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

There is no "API for LilyPond", and that does not even make sense.  You
are possibly talking about "Coding Standards" which is something totally
different.  APIs are for the computer talking to the computer.  Coding
standards are for people talking to the computer and to other people.

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

That's crap.  If something is not obvious, write down the reasoning
behind it.  Whether you do it in code comments, or in documentation
strings or whatever, write it down.  Don't tell the story just to the
computer, correction, don't tell just the _letters_ of the story to the
computer (telling the story would involve proper factorization).

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

Mike, you write _no_ comments as a rule.  That means that your code is
unmaintainable crap as a rule.  That does not mean that there isn't
unmaintainable crap in the preexisting LilyPond code base, too.  I am
weeding some of it out and designing sane code paths and interfaces to
replace them, fixing the logic and writing documentation.  That's very
hard work and takes likely more than ten times the amount of time than
originally writing it took.

You are _far_ too productive to make it possible for me or anybody else
to go with a fine sieve through _every_ _single_ contribution of yours
even in review and tell you _every_ _single_ place where things fall
apart without a comment or a description or a documentation string or
sensible variable names.

_Wherever_ somebody could ask "what is the idea behind this?", there is
a missing comment or documentation string.  Yes, it is bad with the
preexisting LilyPond code base, but extending LilyPond while keeping
this style is making it exponentially worse.

And make no mistake, even if we are talking about the quality of
uncommented code: it is not rare that I encounter code where I say "this
is so broken and/or handwavy and/or indecipherable, I'll bet it's from
Mike" and am right far more often than I'd like.  If at least the
rationale behind the code were commented, it would not be such a time
sink to analyze and/or fix.

Now recognizing coders by their handwriting is also possible with
excellent coders: it's reasonably easy to figure out whether some TeX
code has been written by Heiko Oberdiek, Hans Hagen, David Carlisle, or
myself.  The average comment density is not particularly high, granted.
But it is definitely non-zero, and it is there for basically everything
of substance _underlying_ the code.

-- 
David Kastrup