Re: succinctness = power

[Ken Anderson <address@hidden>]

At 12:33 PM 5/30/2002, Jeremy Hylton wrote:
> >>>>> "PG" == Paul Graham <pg@archub.org> writes:
>
>   PG> Incidentally, I am not a big fan of comments.  I think they are
>   PG> often an artifact of using weak languages.  I think that
>   PG> programming languages should be a good enough way to express
>   PG> programs that you don't have to scrawl additional clarifications
>   PG> on your source code.  It would be a bad sign, don't you think,
>   PG> if a novelist had to print notes in the margins saying "she left
>   PG> without saying anything because she was angry about the trampled
>   PG> petunias?"  It is the job of the novel to make that clear.  I
>   PG> think this is what SICP means when they say "programs must be
>   PG> written for people to read, and only incidentally for machines
>   PG> to execute."  I use comments mostly to apologize/warn about
>   PG> hacks, kludges, limitations, etc.
>
>I'm a big fan of comments.  I find that they are often useful to
>explain the why of a program where the code expresses the how.  One
>example of a very helpful comment is a long note at the beginning of
>Python's dictionary (hash table) implementation.  I'll included at the
>end of the message.

I agree that this kind of overview documentation is very important.

Kent Beck says that no more than 1% of the lines of code he writes is 
documentation.  He does work hard at making the code he writes clear.

Documentation generators, like javadoc are useful, but sometimes 
documentation takes on a life of its own.  I once looked at the 73 uses of 
EventListenerList and found 25 cases where the documentation did not match 
the code.