Path: csiph.com!x330-a1.tempe.blueboxinc.net!newsfeed.hal-mli.net!feeder1.hal-mli.net!news.linkpendium.com!news.linkpendium.com!news.snarked.org!newsfeed.news.ucla.edu!usenet.stanford.edu!news.kjsl.com!news.alt.net!news.astraweb.com!border6.newsrouter.astraweb.com!not-for-mail From: Ben Finney Newsgroups: comp.lang.python Subject: Re: The worth of comments References: X-Public-Key-ID: 0xAC128405 X-Public-Key-Fingerprint: 517C F14B B2F3 98B0 CB35 4855 B8B2 4C06 AC12 8405 X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-pubkey.asc X-Post-From: Ben Finney Date: Fri, 27 May 2011 11:42:54 +1000 Message-ID: <87sjs0apgh.fsf@benfinney.id.au> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) Cancel-Lock: sha1:3vcmBk3TjWFxUu/IRBoeXpGL7Xc= MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Lines: 26 Organization: Unlimited download news at news.astraweb.com NNTP-Posting-Host: eed2afb3.news.astraweb.com X-Trace: DXC=flX24iBPPSm1m]JSMD?cjjL?0kYOcDh@j7^o:UA4R?ceS`HWH2Uf3?i]G;2>V^?kWcbEW9A[5UK?eNZ[SL`C\Kgc9n]_nU:hFYh Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:6359 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 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. -- \ “If this is your first visit to the USSR, you are welcome to | `\ it.” —hotel room, Moscow | _o__) | Ben Finney