Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!aioe.org!feeder.news-service.com!news2.euro.net!newsfeed.xs4all.nl!newsfeed5.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail Return-Path: 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; 'bug': 0.02; 'subject:Python': 0.06; 'comment,': 0.09; 'imho.': 0.09; 'readable': 0.09; 'am,': 0.14; 'wrote:': 0.14; 'angelico': 0.16; 'definition,': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; "function's": 0.16; 'language': 0.18; 'subject:list': 0.19; 'subject:Issue': 0.19; 'written,': 0.19; 'header:In-Reply-To:1': 0.21; 'thu,': 0.22; 'code.': 0.22; 'received:209.85.210.174': 0.23; 'received:mail- iy0-f174.google.com': 0.23; 'code': 0.24; 'do,': 0.25; '(and': 0.25; 'message-id:@mail.gmail.com': 0.28; 'problem': 0.28; 'explains': 0.29; 'updated': 0.29; 'it.': 0.31; 'programmers': 0.31; 'to:addr:python-list': 0.33; 'comment': 0.33; 'rather': 0.34; 'chris': 0.34; 'richard': 0.34; 'sometimes,': 0.35; 'languages': 0.35; 'actual': 0.36; 'received:google.com': 0.37; 'received:209.85': 0.37; 'depend': 0.37; 'but': 0.38; 'subject:: ': 0.38; 'comments': 0.39; "i'd": 0.39; 'received:209': 0.39; 'to:addr:python.org': 0.39; 'more': 0.60; 'subject:, ': 0.60; 'stop': 0.62; 'piece': 0.63; 'valuable': 0.66; '26,': 0.67; 'readers': 0.68; 'care': 0.72; 'embrace': 0.84; 'flame': 0.84; 'place?': 0.84; 'subject:Vol': 0.84; '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=UgYxjrN9hFm70AF59HrBjufxPJ4eg9Ua6sNCYktNOyI=; b=p2rC8yHb6OXWDc1BaOjvT9t1McBPWIh3nT2tJRP0eOve5TCGerYbuagN76KuMoMzyp YqrSQG8HUAWWdANREbiWS2cBqImtWHWEn/2Bc5RBgFadGLHol5rZXxJFcppF4iQOUaKO 17I/kpmMWZxgO7KrPwBCigKhOnIgFN2Z8Kw38= 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=YOZ4Cvds7at1EjRbZpiQt//5ojJdh6BrzBnirJvKK739wWVRSSQ8SDT16wXw0t1VB1 HqHnoVA7zdCKszhu7RbgYksM8sfuZ6NippAYjnycgdvIR2m+K9ajq813eUzXCa8aW9vc 5GX7d3EIoZTXQTWX7/8pfLj+4tTcgq4YbvaZk= MIME-Version: 1.0 In-Reply-To: References: Date: Thu, 26 May 2011 14:06:56 +1000 Subject: Re: Python-list Digest, Vol 92, Issue 221 From: Chris Angelico 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 21 NNTP-Posting-Host: 82.94.164.166 X-Trace: 1306382819 news.xs4all.nl 49048 [::ffff:82.94.164.166]:33110 X-Complaints-To: abuse@xs4all.nl Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:6292 On Thu, May 26, 2011 at 10:58 AM, Richard Parker 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