RE: succinctness = power

["Christopher Barber" <address@hidden>]

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

Exactly.  Comments are important when multiple people must use the code in
question, but they must be maintained and this requires discipline.  I can
see that if you were the only person touching a body of code, you might not
want to bother with comments, but I know that there have been times I have
looked at my old code and wished I had added a few more comments.  If you
are writing API's for others to use, you obviously have to maintain
documentation for the API, and it is more likely to be kept up-to-date if
the documentation lives with the code.  It is not hard to maintain comments;
you just have to decide that you are going to do it.

- Christopher