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

Re: succinctness = power

> Date: 27 May 2002 19:00:26 -0000
> From: Paul Graham <pg@archub.org>
> 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.
> --pg

In my view there are two kinds of comments.  One is the kind you describe
(apologies/warnings about hacks etc.), and the other is basically an
interface specification, which says what the function does, what arguments
it takes, what it returns, and any other relevant information that is
needed to use the function in a black-box manner.  If your code doesn't
have this, it's going to be pretty hard for someone else to use.  Now maybe
what this really means is that programming languages don't have good enough
ways to specify interface information of this sort, and this may be
something that current languages could do better.  You see a trend in this
direction in java and C#, where you can embed interface information in
comments.  Python and common lisp have docstrings which can be used in this
manner, but I'm thinking of something more structured.