| Re: [frogs] Frog's Lament |
[ Thread Index |
Date Index
| More lilynet.net/frogs Archives
]
Carl Sorensen wrote Thursday, November 26, 2009 4:31 PM
On 11/26/09 2:56 AM, "Marc Hohl" <marc@xxxxxxxxxx> wrote:
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.
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.
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.
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.
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!
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.
Trevor
---
----
Join the Frogs!