Re: [frogs] Frog's Lament

[Carl Sorensen <c_sorensen@xxxxxxx>]

On 11/26/09 2:56 AM, "Marc Hohl" <marc@xxxxxxxxxx> wrote:

> Hello all,
> 
> I followed the (partly very emotional) discussions about
> (un)documentated code
> with great interest, and aside from the fact that I neither have the
> technical
> arguments nor the knowledge, I mostly agree with David Kastrup.
> 
> As a frog, I feel supported very well from Carl et al., but nevertheless,
> I see myself still throwing little stones at random in the pond, looking at
> the ripples on the surface (to stay in the picture).
> 
> Well documented code is crucial in such a project for other developers
> to jump
> on the train, so learning by RTF code isn't fun (as mentioned elsewhere) -
> for me, it's annoying, it's frustrating, and it keeps me persistently
> feeling
> too stupid even for the easiest tasks.
> 
> Ok, there are some who have absorbed the philosophy of lilypond, so they
> can deliver
> great patches without asking one question on the list (kudos to them!),
> but I want
> to improve lilypond, too, and I am not this sort of guy. And I think I
> am not the only one ...
> The list support is great, but in the time necessary to answer all my
> questions on
> a specific problem again and again, that person would have solved the
> task I am working
> on more quickly and perhaps even more consistently that I do. Ok, this
> is not the spirit
> of the whole frog thing, but I hesitate bothering developers with my
> questions.

Two things come to mind here:

1) When any of us asks a question on the list and gets an answer, we ought
to add it to the CG.  We can either do it by writing a patch, or by writing
some text that will get added to the CG.

I volunteer to add text to the CG as part of my Frogmeister
responsibilities, but I don't have the time to follow all the questions and
answers and turn them into stuff that will be added to the CG.

2) I think that it always takes developers less time to answer questions
than to write the patch that you will produce.  It will take you longer to
write the patch than it would take some more-experienced developer, but
you're also developing some capability.

> 
> So, while the code indentation policy is very strict, why don't we do
> something
> similar concerning the documentation? If only patches are pushed that
> are well documented,
> at least the improvements will be documented, and perhaps the developer
> has some time
> to document bits and pieces of the code he is referring to, too.

I think this is a great idea.  I think we have been following this policy
somewhat recently (e.g. we have asked for doc strings to be written before
the patch is accepted).  I'll try to watch out for this more in the future.

> 
> It is clear that fully documentated lilypond code can't be written from
> scratch,
> but we have to start somewhere, and if the patch doc policy is as
> restrictive as
> the patch indentation policy, this will ease the work for future
> developers significantly.
> 

The place where I have the most problems is in the C++ guts of LilyPond.
And there are relatively few patches that are applied in this area.  So,
while I think that asking for patches is good, I think that asking for
improved descriptions in the CG is even better.

> Then, I miss some general information of the future goals. Ok, the bugs
> should be
> eliminated, but rumor says that there are efforts to move functionality
> from c++ to scheme.
> Is this true? 

As far as I know, the goal to move functionality from c++ to Scheme is not a
means to eliminate any use of c++ code.  To me, it appears that what is
hoped is that all of the management of the parsing, iterating, engraving,
and translating will remain in c++, but that all of the output creation
(both graphical and MIDI) will be in scheme.  If that is the case, then
everything can be modified in Scheme, and c++ is only needed when a new
engraver or translator is to be created.

> If yes, would it be for instance possible to write a
> interface in c++
> (kind of a meta-engraver) to allow engravers being coded in scheme? For
> people
> deeply involved in the internals, this doesn't seem to be very
> important, but I think
> it would improve the situation immediately.

I know that David has expressed a desire to have this work as well.

Personally, I think it would be very cool to have that work.  But I don't
know if it's even feasible, or how much it would reduce the performance of
LilyPond.  But if it could be done, and the performance is satisfactory, it
would certainly help future development.

> 
> I learned scheme for working as a frog, and now I am at a point where
> even the simplest
> tasks (seem to) require some additional c++ coding, so I will have to
> learn c++, too.

I'm confused by this description that "the simplest tasks require c++
coding."  Can you give me an example of such simplest tasks?

> On the other hand, my c++ code may soon be useless if someone writes
> such a meta engraver
> interface; therefore I hesitate to put much energy into learning a new
> language.

I don't see a meta engraver interface coming in the near future, if ever.
If you need a new engraver, then I think the time spent to write the
engraver would be well-spent.

> Besides, not having to compile the sources ever and ever again makes
> development much
> easier, quicker and more reliable.

Yes, this is true.

> 
> There has been a lot of emotions and some kB of mails in the last days,
> so there is
> a strong will to improve lilypond; without insulting anyone, I would ask
> the core
> developers to try to see the whole story from somebody's point of view
> who has no
> clue where to start, limited time, but nevertheless the will to make
> things better.
> The community cannot afford to drive away possible developers by giving
> them the feeling
> that there is some inner circle where information flows and where the
> beginning
> coder has no entry (sort of: "You don't understand the code yourself? Go
> playing with
> your toys then.") I don't think this is the case, although it sometimes
> seems to be.

I agree with both of your points.  There is no inner circle that wants to
hold all knowledge close.  And sometimes it seems that there is.

To me, the best way to resolve this problem is to get the knowledge out of
the gurus heads' and into the documentation.  But that is not likely to
happen by the gurus writing the documentation.  Instead, we less-experienced
developers need to document things as we learn them.

Is it fair that beginners need to document in addition to writing code?
Probably not.  But we beginners need to improve our understanding, and one
of the best ways to improve understanding is to explain it to others.  And
that will help us in our desires to contribute.

Thanks for helping clarify the issues.

Carl


---
----
Join the Frogs!