[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: succinctness = power
At 12:33 PM 5/30/2002, Jeremy Hylton wrote:
> >>>>> "PG" == Paul Graham <firstname.lastname@example.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