Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!selfless.tophat.at!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.019
X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'instance,': 0.05; 'subject:Python': 0.06; 'used.': 0.07; 'figuring': 0.09; 'foo': 0.09; 'readable': 0.09; 'pm,': 0.10; 'wrote:': 0.14; '*why*': 0.16; 'agree.': 0.16; 'algorithmic': 0.16; 'angelico': 0.16; 'docstrings': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; 'organic': 0.16; 'subject:list': 0.19; 'part,': 0.19; 'subject:Issue': 0.19; 'header:In-Reply-To:1': 0.21; 'figure': 0.21; '(but': 0.22; 'thu,': 0.22; 'so.': 0.22; 'received:209.85.210.174': 0.23; 'received:mail- iy0-f174.google.com': 0.23; 'code': 0.24; "doesn't": 0.25; 'not.': 0.26; 'example': 0.27; 'message-id:@mail.gmail.com': 0.28; 'extent': 0.29; 'code,': 0.29; 'it.': 0.31; 'usually': 0.32; "can't": 0.32; 'done,': 0.32; 'steven': 0.32; 'tend': 0.32; 'to:addr:python-list': 0.33; 'generally': 0.33; 'comment': 0.33; 'lines': 0.33; 'rather': 0.34; '...': 0.34; 'chris': 0.34; "d'aprano": 0.35; 'several': 0.36; 'table': 0.37; 'received:google.com': 0.37; 'received:209.85': 0.37; 'another': 0.37; 'pretty': 0.37; 'think': 0.38; 'anything': 0.38; 'but': 0.38; 'though': 0.38; 'todo': 0.38; 'subject:: ': 0.38; 'some': 0.38; 'comments': 0.39; 'explain': 0.39; 'should': 0.39; 'received:209': 0.39; 'to:addr:python.org': 0.39; 'worth': 0.60; 'subject:, ': 0.60; 'best': 0.60; 'your': 0.60; 'matter': 0.63; 'comments,': 0.65; 'further': 0.65; '26,': 0.67; 'superior': 0.72; '"look': 0.84; 'comment.': 0.84; 'subject:Vol': 0.84; 'obvious,': 0.93; 'was.': 0.93; 'greatest': 0.95; 'absolutely': 0.98
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:in-reply-to:references:date :message-id:subject:from:to:content-type; bh=Q6J7Rt5RfuGSyIhEZEbbtpICg0lF7TlvpRTjwZ2DF6w=; b=YWN8NL15P2nbKSLQbCJMC91bVz5mp04rXVhwzEHlIAFzJSbxUSyK4bptaw9Lpv0dEs l+y+mMbvM/8G3E+da+5ypoFWgB22gO7Oxfr50DdMRreP3bXhlChCWP3y6yaUtKm0R2TI SJbbyarSSXVTDaQkwsdnX73rZl24/ZVBi9fhg=
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; b=MMFHo7nj7XASkP0JH6b1KFeTrsO+Oo6fsFhoACP682KhuXx2AtICUzVKOk2+aKu/9G AsHWq7iBPdhC/s+1QOpuSIljXFt7yon6jcZzhLK78fGB+8iIJgxuVJliI+KHoSnF3EYO HykKk1nRlW7oRWsJyLm1hfnhDQ7581JwcZXDc=
MIME-Version: 1.0
In-Reply-To: <4dde265c$0$29997$c3e8da3$5496439d@news.astraweb.com>
References: <mailman.8469.1306366341.9058.python-list@python.org> <F6DB2229-6123-4C1A-AFAE-1342DEAC841A@comcast.net> <mailman.2107.1306382819.9059.python-list@python.org> <4dde265c$0$29997$c3e8da3$5496439d@news.astraweb.com>
Date: Thu, 26 May 2011 20:25:29 +1000
Subject: Re: Python-list Digest, Vol 92, Issue 221
From: Chris Angelico <rosuav@gmail.com>
To: python-list@python.org
Content-Type: text/plain; charset=ISO-8859-1
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.2115.1306405533.9059.python-list@python.org>
Lines: 41
NNTP-Posting-Host: 82.94.164.166
X-Trace: 1306405533 news.xs4all.nl 49175 [::ffff:82.94.164.166]:54202
X-Complaints-To: abuse@xs4all.nl
Xref: x330-a1.tempe.blueboxinc.net comp.lang.python: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