Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!aioe.org!feeder.news-service.com!news2.euro.net!newsgate.cistron.nl!newsgate.news.xs4all.nl!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.030 X-Spam-Evidence: '*H*': 0.94; '*S*': 0.00; 'documenting': 0.07; 'names.': 0.07; 'python': 0.08; '(it': 0.09; 'inclined': 0.09; 'variables,': 0.09; 'am,': 0.14; 'described': 0.14; 'wrote:': 0.14; 'received:mail.comcast.net': 0.16; 'self-': 0.16; 'occurred': 0.19; 'to:2**1': 0.20; 'lines,': 0.23; '-----': 0.23; 'code': 0.24; 'url:mailman': 0.26; 'classes': 0.26; "i'm": 0.27; 'subject:': 0.30; 'url:listinfo': 0.30; 'blocks': 0.30; 'x-mailer:microsoft outlook express 6.00.2900.5931': 0.30; 'relatively': 0.32; 'to:addr:python-list': 0.33; 'list': 0.33; '(for': 0.33; 'comment': 0.33; 'rather': 0.34; 'sent:': 0.34; 'however,': 0.34; 'describe': 0.34; 'richard': 0.34; 'from:': 0.36; 'instead.': 0.37; 'interview': 0.37; 'thursday,': 0.37; 'url:python': 0.38; 'received:76': 0.38; 'screen': 0.38; 'url:org': 0.38; 'but': 0.38; 'subject:: ': 0.38; 'comments': 0.39; 'should': 0.39; 'to:addr:python.org': 0.39; 'worth': 0.60; 'results': 0.60; 'more': 0.60; 'subject': 0.62; 'phone': 0.63; 'selected': 0.67; '26,': 0.67; 'subject:The': 0.69; 'low': 0.73; '11:50': 0.84; 'full.': 0.84 From: "Patty" To: "Richard Parker" , References: <1CCA9F21-28E8-43CF-BBE0-D4080D1E6993@comcast.net> Subject: Re: The worth of comments Date: Thu, 26 May 2011 13:30:10 -0700 MIME-Version: 1.0 Content-Type: text/plain; format=flowed; charset="iso-8859-1"; reply-type=original Content-Transfer-Encoding: 7bit X-Priority: 3 X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook Express 6.00.2900.5931 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6090 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: 41 NNTP-Posting-Host: 82.94.164.166 X-Trace: 1306443753 news.xs4all.nl 49181 [::ffff:82.94.164.166]:43810 X-Complaints-To: abuse@xs4all.nl Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:6343 ----- Original Message ----- From: "Richard Parker" To: Sent: Thursday, May 26, 2011 11:50 AM Subject: The worth of comments > On May 26, 2011, at 4:28 AM, python-list-request@python.org wrote: > >> 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) > > (It occurred to me that I should use a specific subject for this > discussion.) > > I'm less inclined to use comments on each line, or selected lines, but > rather use block comments instead. They require more thought and time to > write; however, the intended functionality of the code that follows can be > described in full. > > -- > http://mail.python.org/mailman/listinfo/python-list > > Hello Richard - I was recently complimented in a phone screen interview for including comment blocks exactly as you describe above. Regards, Patty