Re: Uncommented code in LilyPond

[David Kastrup]

"address@hidden" <address@hidden> writes:

> My code tends to be rather sparsely commented (if at all) because, as
> you state above, there is an internal logic to LilyPond created by the
> original authors that is uncommented but consistent, and once one
> understands that, one's work fits into that logic.

But you are not one of "the original authors" and so your code has a
different style and logic, and the fittings are differently and worth
mentioning.  Well, if we switch off hero worship for a moment, it's not
like I don't want to hit Han-Wen and Jan over with a comment-eliciting
clue bat as well.  They might cite the excuse that they did not consider
it possible that LilyPond survived beyond their active call of duty, but
that excuse has grown old by now.

We probably need a redocumentation project where every developer is
assigned one source file in a language he is supposed to understand and
is left with the task of leaving it in a documented state where he feels
comfortable saying that he knows how it fits together with other files,
what LilyPond language constructs will trigger its use under what
circumstances, what choices were taken in the code, and that he is
confident that the next one reading this file will, by virtue of its
comments, be in the same position within half an hour.

If he has questions, he will have the right to ask them from people that
(short of code reformatting) "git gui blame" declares the responsible
party, as long as they are still alive.  In my book, this takes priority
over any new work they might want to be doing instead.  Answering
questions does not take a lot of time.

It would also make sense to remove the obligation to go through any kind
of review for comment-only changes where the submitter _knows_ that his
analysis of the intent is correct ("knows" rather than "has convinved
himself"), either by an _exhaustive_ analysis, or by being or asking the
original author.

> As for the valgrinding, a lot of my work in LilyPond is knowing what I
> want to do on thing X but not knowing how thing X is linked to other
> things in the code base.

You don't find security problems by valgrinding, and things are similar
for _potential_ memory problems.  Either have the tendency to come into
view when you don't really want them rather than when you politely
invite them.

> For example, I'll know how grob X uses grobs to find its extents, but
> the reverse is much more difficult - knowing what grobs use grob X to
> find their extents.  So it's true that when I start solving a problem
> it is often well beyond my understanding of how a single grob is
> interconnected to all other parts of LilyPond.  If I let this stop me,
> I wouldn't have done any work on LilyPond.

Sure.  But at one point of time, we want the help and support and
contributions from people that _will_ get stopped by this.  And even we
don't cared about those, we don't want to have the slowdown and
concentration hit on those that _will_ eventually figure it out on their
own.  We don't want to _waste_ our human resources on inefficient
processes, and figuring out what code does is most efficiently done by
the person writing the code.  If he has to do the job anyway, there is
no point that the next person looking at the same files has to do the
job again.

> I don't mind going through the code, file by file, and writing
> comments everywhere.  I understand most of it and if you think that'd
> lead to better maintainability then it is worth it.  I'll try to do
> 3-4 files a week.

I think more of 6 people doing one randomly assigned file a month.  It
is ok if they feel they want to do more, but this will already cause
quite a load of private mail on the original authors.

> And I definitely didn't mean to not respond to one of your suggestions
> - I forgot to get around to writing that comment you asked for as I
> was distracted by other things in the patch.  Nor do I mean to
> ridicule you - the Strong Bad Tandy 400 comment was because I don't
> think there's a real efficiency tradeoff (I did some tests and in fact
> there isn't).

I suppose Keith is hallucinating his results then.  O(lg n) against O(1)
for a single access is a trade off, in particular with a big constant
factor.  Searching for data when you could arrange for it to be at a
certain place is a tradeoff.  Maintaining a search data structure where
things are entered and removed according to some complex scheme rather
than by garbage collection (which is bad enough) is error-prone, with a
non-zero probability of indefinite growth of the data structure.

> I do take your suggestions very much to heart, however, and am
> experimenting w/ a new way of going about it that uses only vectors
> and is much clearer.

Thanks.  LilyPond is complex enough without adding unneeded and
uncommented complexity at every corner.

-- 
David Kastrup