Re: "Documentation by paper"

[kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner)]

    well, that's true for pretty much any word in any natural language.
    it's generally expected that people can resolve ambiguities from
    context (even in math papers).  and in programming, the actual program
    is usually a pretty strong disambiguator.

It most certainly *is not*!  The problem is that programs are not perfect and
may have bugs.  The whole purpose of the documentation is to describe what
the program is *supposed* to do.  If you don't have the details of what it's
supposed to do, you can't tell if it's correct or not.

And these subtle variations in definition are precisely the places where
bugs will reside!

    everyone already agrees that readable code is a good thing.  it
    isn't hard to handle that on a case-by-case basis.  "it took me a
    while to figure out what this meant.  how about this patch for
    clarity?"

The problem is that it doesn't get done!  I've sent about a half dozen of
such messages and in only *one* of those cases did anybody do anything
about it.

That's why we need strict documentation standards that are enforced *before*
code is accepted.