Python-list Digest, Vol 92, Issue 221

[Chris Angelico]

On Thu, May 26, 2011 at 8:07 PM, Steven D'Aprano
<steve+comp.lang.python at pearwood.info> wrote:
> Another use for comments is to explain *why* rather than *what*. No
> matter how readable your code is, if you don't understand why it is done,
> you can't effectively maintain it. If the why is obvious, you don't need
> a comment.

That's what my (contrived) example was. I also often have comments
that are leftovers from the pseudocode stage; for instance, iteration
1:
//TODO: Look up foo in some table and figure out which bar should be used.

Iteration 2:
//TODO: Look up foo in the bar_foo table and figure out which bar
should be used.
legal_bar = bar_foo[foo]; bar=legal_bar[0];

Iteration 3:
//Figure out which bar should be used
legal_bar = bar_foo[foo];
... some algorithmic way of figuring out the best one ...

When it leaves TODO status, anything that's inherently obvious ("Look
up foo in the bar_foo table") gets trimmed, but the statements of
purpose tend to remain. Especially if the "figuring out the best one"
is several lines of code, it makes sense to keep that comment. But
because of the organic growth of the code, the comment will usually
still bracket the "look up foo in table" part, even though the comment
doesn't have anything to do with that.

Is the comment inappropriate? I don't think so. Is it perfect?
Definitely not. But it's still generally worth keeping.

But I absolutely agree. The code ought to be self-documenting to the
greatest extent possible (but no further - don't just create
variables/constants for absolutely no reason than to embody
documentation). Docstrings and autodoc comments are superior to
general comments, although IMHO all three are pretty much the same
thing.

Chris Angelico