Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #6309

Re: Python-list Digest, Vol 92, Issue 221

Show key headers only | View raw

On Thu, May 26, 2011 at 8:07 PM, Steven D'Aprano
<steve+comp.lang.python@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

Back to comp.lang.python | Previous | Next — Previous in thread | Find similar | Unroll thread

Thread

Re: Python-list Digest, Vol 92, Issue 221 Chris Angelico <rosuav@gmail.com> - 2011-05-26 14:06 +1000
  Re: Python-list Digest, Vol 92, Issue 221 Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-05-26 10:07 +0000
    Re: Python-list Digest, Vol 92, Issue 221 Chris Angelico <rosuav@gmail.com> - 2011-05-26 20:25 +1000

csiph-web