Python-list Digest, Vol 92, Issue 221

[Chris Angelico]

On Thu, May 26, 2011 at 10:58 AM, Richard Parker
<r.richardparker at comcast.net> wrote:
> It's time to stop having flame wars about languages and embrace programmers
> who care enough about possible future readers of their code to thoroughly
> comment it. Comments are far more valuable than the actual language in which
> the code is written, IMHO.

The problem with comments (and documentation in general) is that they
are often imperfect. If the code is absolutely opaque but it has a
comment next to it, you still have that niggling doubt: has the
comment been updated whenever the code has? Was it even accurate in
the first place? (Comments often say what a piece of code _ought_ to
do, but the code might have a bug in it. And sometimes, that bug ends
up being part of the function's definition, and people depend on it.)
I'd rather have both - reasonably readable code AND a comment, where
the comment explains the intent behind the code.

// allow space for frobnostication
height += BTN_HEIGHT;

Chris Angelico