Re: [frogs] Frog's Lament

[Marc Hohl]

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
> learned.
>
> 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
> CG.
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!
Exactly.

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.

Marc