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

Groups > comp.lang.python > #6292 > unrolled thread

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

Back to article view | Back to comp.lang.python

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  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

#6292 — Re: Python-list Digest, Vol 92, Issue 221

On Thu, May 26, 2011 at 10:58 AM, Richard Parker
<r.richardparker@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

[toc] | [next] | [standalone]

#6308

On Thu, 26 May 2011 14:06:56 +1000, Chris Angelico wrote:

> On Thu, May 26, 2011 at 10:58 AM, Richard Parker
> <r.richardparker@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. 
[snip more stuff I agree with]

It's not the lack of perfection, since no code is perfect, but that 
comments are frequently missing, obsolete, incorrect, or inane: i.e. 
actively harmful rather than just imperfect.

The classic example of what not to write as a comment:

x += 1  # add one to x


One of the regulars here -- Aahz -- often has this quote as his sig:

    "At Resolver we've found it useful to short-circuit any doubt 
     and just refer to comments in code as 'lies'."
     -- Michael Foord paraphrases Christian Muirhead on python-dev,
        2009-03-22


My experience is that comments in Python are of relatively low 
usefulness. (For avoidance of doubt: not *zero* usefulness, merely low.) 
I can name variables, functions and classes with sensible, self-
documenting names. Why write:

x = get_results(arg)  # x is a list of 1 or more results
[... much later]
for y in x:
    # process each result in turn
    do_something_with(y)


when I can write this?

results = get_results(arg)
[...]
for result in results:
    do_something_with(result)


It's better to write self-documenting code, than code + comments.


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.

But for me, the main reason # comments are of relatively little use in 
Python for me is because I write *tons* of docstrings and doctests. Any 
comment which could be useful to know at run-time goes into the 
docstring; what's left over, if anything, becomes a # comment. Between 
self-documenting code and docstrings, I hardly write any # comments.



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#6309

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

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web