Re: Uncommented code in LilyPond

[Graham Percival]

On Mon, Sep 03, 2012 at 11:45:50AM +0200, David Kastrup wrote:
> "address@hidden" <address@hidden> writes:
> 
> > As a frequent producer of uncommented code that pushes into a code
> > base with uncommented code, I am more than willing to put comments.
> > However, I'll say that a lack of comments has never stopped me from
> > understanding how something works in LilyPond.
>
> There is a simple rule: debugging code is twice as hard as
> writing it.  If you want to be able to debug your code, don't write at
> the limit of your capacities.

That's a paraphrase; full quote is:
"Everyone knows that debugging is twice as hard as writing a
program in the first place. So if you're as clever as you can be
when you write it, how will you ever debug it?"
- Brian Kernighan, co-author of the first book on C.

> Coding is not composing.  The work is
> never finished, and other people need to be able to continue what you
> started.  And understanding foreign code is twice as hard as
> understanding your own.  If you are writing at the limit of your
> capacity, it will take somebody twice as smart as you are to work with
> your code.

Yes.

> Yes, I _am_ a silly old fool, but I have written a lot of code in my
> lifetime.

Yes.  (umm, the "a lot of code", not "silly old fool")

Mike, I also used to be a young programmer who thought that my
code was obvious.  I mean, I even re-wrote the program for my
Masters thesis 3 times to improve the design, so obviously I cared
a lot about maintainability!   (hah)

Fast-forward two years, when I'm trying to make it compile on
Ubuntu 10.04 instead of MacOSX 10.4.  (heh, I just noticed the
coincidence in the numbers)  I mean, I used cross-platform
libraries, and at the time I had tested it with Debian Sarge.  So
it should have been easy, right?  Well, no.  It took me about a
day to figure out what I had been doing and fix the compatibility
issues.  And that was code that was entirely written by myself,
not touched by anybody else, and a mere two years later.


Comments aren't just something that senior programmers invented to
torture junior programmers with.  They really help.  Nobody really
understands how much they help until they spend hours looking at
code that they themselves wrote in the past.  When I wrote stuff,
I really, really thought that it was totally obvious.  I
distinctly remember being very proud of my design and code.  But
now I also remember cursing the idiot (myself) who wrote that code
as I tried to figure out what was happening.

I think that any time that a LilyPond developer complains that
the code is too hard to understand, the patch should automatically
move to Patch-needs_work.  Automatically.
If there's a long discussion and there's overwhelming opinion from
other developers that the code is fine, then we could ignore the
dissenting developer.  But unless there's *overwhelming* opinion
that the patch is fine, I think that a single complaint of
readability should render the patch un-pushable.

- Graham