Re: [frogs] Frog's Lament

[David Kastrup]

"Trevor Daniels" <address@hidden> writes:

> 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!

When the operation is particularly obscure, it likely needs to be done
differently, not documented.

In the end, the programmer will need to read the code in order to know
what is done.  That is fine.  And it does not get clearer by writing the
same thing in English.

But reading the code does not tell the programmer _why_ something is
done.  And that is what needs documentation.

> 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.

But I'd like to see an identical comment in every engraver _linking_ to
the right section in the CG.  If reading the code does not tell me the
story, it should at least tell me _where_ I get to read the story
instead of assuming that I have already learnt all documentation by
heart and know _what_ is documented and _where_.

-- 
David Kastrup