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 _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
