Re: state of the release: the Good, the Bad, and the Ugly

[David Kastrup]

Carl Sorensen <address@hidden> writes:

> On 5/27/10 7:05 AM, "David Kastrup" <address@hidden> wrote:
>
>> Valentin Villenave <address@hidden> writes:
>> 
>>> On Wed, May 26, 2010 at 3:39 PM, Graham Percival
>>> <address@hidden> wrote:
>>> nobody really felt that actually committing the patches was their job.
>> 
>> The problem is that committing a patch suggests some basic
>> responsibility.  If a patch is not within the comfort zone of
>> prospective committers, it tends to rot.
>
> I think that there is truth in both of those issues.  For Frogs, I
> have the responsibility of committing patches.  But for David's patch,
> it's outside my comfort zone.  Han-Wen and Nicolas reviewed the patch,
> and thought it looked fine.  I dropped the ball in committing it.

Why would it be your responsibility?  And if it were: where is the point
in making someone responsible for committing patches he is not
comfortable with?

>> It does not help with explaining the internals of Lilypond all too
>> much, but then nothing does right now.
>
> In my opinion, the lack of a clear explanation of the internals of
> LilyPond is the biggest obstacle for getting started in development.

I am not all too sure.  For starting development, it is more important
to know what you _don't_ need to touch for a given task than what you
do.  And if you do need to touch a lot, then it may be a sign that the
code (and its responsibilities) is not organized well.

>> In a healthy project, contributors come and go.  If you instead only
>> see the same faces leaving and returning, something is amiss that
>> makes starting to contribute hard.
>
> Yes, this is true.  In your opinion, what are the top 3-5 things that
> make starting to contribute hard?

Properties.  There are tweaks, overrides, sets.  Some of them work on
some properties, and there is no user level coherence to what you need
to do on what and why.  Yes, I had some fits about that already, and
some people repeatedly told me I am an awful child for keeping up the
"why, why" questions and that things were just so.  But I am arrogant
enough to say that something that can't be explained to me in a way that
I understand it is a mistake in a programmer interface.  And we are
talking about a _user_ interface, one you can't avoid using.

Write-only code.  If you try figuring out what the engravers and
performers an contexts do and look in the code, you'll see a maze of
twisty little passages and convenience macros for declaring things.
What you don't see are comments.  If "outsiders" contribute anything,
they are prodded to simplify and document their code until a "regular"
can look over it and understand it without trying.  There is some nice
idea behind it, but it turns into a failure because of several reasons:
a) the resources available for review from the "regulars" are scarce, so
only trivial code can pass their examination.  That means that
non-trivial extensions of Lilypond remain the privilege of regulars.
b) the regulars don't apply the same standard to their own code.  Or
rather, they consider their code fine when _they_ feel they understand
it.  After all, their time is scarce.
The resulting code is maintainable only by regulars: either because it
is trivial, or because they wrote it themselves without investing the
effort to make it maintainable rather than just working.

Complete lack of documentation of Lilypond's structures.  Instead, one
is pointed to a diploma thesis centered about music streams, a concept
that does not actually exist in Lilypond.  The thesis talks about
engravers returning a flag to indicate whether they accepted a certain
event.  The respective functions in the C++ classes are void: they don't
have the option of accepting an event.

Complete lack of consideration for Midi: there is no way in the world
that a user, or programmer can design and implement some engraving
facility and also implement some Midi results: all manuals are
effectively silent about Midi: there is no information at all about how
to do _anything_ in that area.  But that means that most contributions
are deficient: they only lead to visual results, ignoring the audible
ones.

Complete lack of consideration for Scheme in Lilypond's processing flow.
Scheme is used in a callback manner, but everything worth happening is
tied together using C++ classes.  Opaque C++ classes, without Scheme
equivalents.  Considering that Scheme has been made part of Lilypond in
the first 10% of its life span, that's not really impressive.

When programming without comments, with macros (I thought C++ stylistic
conventions poo-pooed excessive use of macros) and so on, one could at
least give following generations the courtesy not to do it in a
low-level language.

-- 
David Kastrup