[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: succinctness = power

At 27 May 2002 19:00:26 -0000, Paul Graham wrote:
> Incidentally, I am not a big fan of comments.  I think they
> are often an artifact of using weak languages.  I think 
> that programming languages should be a good enough way to
> express programs that you don't have to scrawl additional
> clarifications on your source code.  It would be a bad
> sign, don't you think, if a novelist had to print notes
> in the margins saying "she left without saying anything
> because she was angry about the trampled petunias?"  It is 
> the job of the novel to make that clear.  I think this is 
> what SICP means when they say "programs must  be written 
> for people to read, and only incidentally for  machines to 
> execute."  I use comments mostly to apologize/warn about 
> hacks, kludges, limitations, etc.

[ Apologies for catching up to this thread so late... ]

Would you, by extension, consider an API's documentation to be an
artifact of a weak language? After all, if the programming language
were well designed, I should just be able to read the code and, from
that, know how to use the GUI library?

That can't be right. Similarly, a few lines of comments here and there
can give an overview of how a bunch of cooperating routines accomplish
their goal. The analogy shouldn't be to a novel, but to a technical
paper. The introductory exposition is critical so the reader doesn't
lose the forest for the trees.

As others have pointed out, the problem is that programmers do not
maintain the comments as they maintain the program. I think that this
is an entirely different problem. The standards for "quality" in the
software industry are about zero, so its not surprising that people
just ignore such comments -- and we all suffer for it!