Path: csiph.com!x330-a1.tempe.blueboxinc.net!newsfeed.hal-mli.net!feeder1.hal-mli.net!border3.nntp.dca.giganews.com!border1.nntp.dca.giganews.com!nntp.giganews.com!news-out.octanews.net!indigo.octanews.net!news.glorb.com!news-out.readnews.com!news-xxxfer.readnews.com!panix!not-for-mail From: Grant Edwards Newsgroups: comp.lang.python Subject: Re: The worth of comments Date: Fri, 27 May 2011 13:54:03 +0000 (UTC) Organization: PANIX Public Access Internet and UNIX, NYC Lines: 34 Message-ID: References: <87sjs0apgh.fsf@benfinney.id.au> NNTP-Posting-Host: dsl.comtrol.com Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Trace: reader1.panix.com 1306504443 3603 64.122.56.22 (27 May 2011 13:54:03 GMT) X-Complaints-To: abuse@panix.com NNTP-Posting-Date: Fri, 27 May 2011 13:54:03 +0000 (UTC) User-Agent: slrn/pre0.9.9-102 (Linux) Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:6390 On 2011-05-27, Ben Finney wrote: > Richard Parker writes: > >> 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've seen plenty of comments who's usefulness was not zero. It was less than zero. >> > I can name variables, functions and classes with sensible, >> > self- documenting names. > > I am largely in agreement with this position (including the ???not *zero* > usefulness??? caveat). > >> 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. > > This I disagree with. If a section of code is interesting enough to > deserve an explanation, then it is better to capture it in a > helpfully-named function with its doc string having the explanation. I consider docstrings to be the same as comments, so there's not really much disagreement. -- Grant Edwards grant.b.edwards Yow! Am I in Milwaukee? at gmail.com