[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [frogs] Frog's Lament

From: Marc Hohl
Subject: Re: [frogs] Frog's Lament
Date: Fri, 27 Nov 2009 09:17:30 +0100
User-agent: Thunderbird (X11/20090817)

Trevor Daniels schrieb:

Carl Sorensen wrote Thursday, November 26, 2009 4:31 PM

While I was learning how to use the Internals Reference
manual I wrote chapter 4 of the Learning Manual to make
it easier for others to follow.  It also benefitted me:
having to write down what I was learning ensured I understood
it properly (well, almost) and the developing chapter
itself became a useful reference source for me to use
as I dug deeper - it was a place to record what I had

I recommend all frogs do this with all aspects of LP
code as a section is understood.

It is possible I shall be embarking on writing an engraver
in the near future.  As this will be my first foray into
the C++ sections of LilyPond I am happy to record what I
find in the CG as I go.  Currently I'm figuring out the
anatomy of an engraver, and it's looking clearer by the
hour (yes, it takes quite a while), and I could contribute
a section on this to the CG after a few more days' study.
I'll need it written down somewhere so I can refer to it
as I begin writing anyway - so it might as well be in the
This is very interesting for me, because it seems that I have
to work on a new engraver, too, so this information will be
*very* helpful. (I think you'll be much faster than I, but otherwise
I am willing to share my experiences, too).
More comments would be an improvement, but I think too
many will destroy the flow of the code when it is being
read by more experienced developers.  I would recommend
a brief overview at the top which sets out the purpose,
structure and method of the code.  Comments intermingled
with the code itself should only appear when the operation
is particularly obscure, but then _must_ appear and be
clearer than the code itself!

We don't need comments like

;; now we add delta-x to x-dim
(set! result (+ delta-x x-dim))

but a brief description of the purpose of the function and its arguments,
perhaps followed by some clarification about the underlying algorithm
is enough. If I have to establish some helper functions, I can mark them
as such with a small comment/short description.

To elaborate on this point with an example, much of the
difficulty with a beginner looking at an engraver is the
nested macros which set up the underpinning structures.
While this is a difficulty, we would not want to see
identical comments in every engraver - that should be
in the CG.
Yes, but there should be a comment pointing at the right place in the CG
in *every* engraver.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]