Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!feeder.erje.net!eu.feeder.erje.net!newsfeed.fsmpi.rwth-aachen.de!eternal-september.org!feeder.eternal-september.org!mx02.eternal-september.org!.POSTED!not-for-mail From: Rob Gaddi Newsgroups: comp.lang.python Subject: Re: Most gratuitous comments Date: Thu, 4 Dec 2014 09:12:41 -0800 Organization: Highland Technology, Inc. Lines: 54 Message-ID: <20141204091241.1f6bf93c@rg.highlandtechnology.com> References: <546d7505$0$12899$c3e8da3$5496439d@news.astraweb.com> <54802e01$0$15926$e4fe514c@dreader35.news.xs4all.nl> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Injection-Info: mx02.eternal-september.org; posting-host="a48e804ab85e47f9d2e8748775b64aeb"; logging-data="25885"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX1+iIb8XcL6KbjBMn9rwkfoc" X-Newsreader: Claws Mail 3.9.3 (GTK+ 2.24.23; x86_64-pc-linux-gnu) Cancel-Lock: sha1:Xu9TDjTCxuEN1uE7AcG3jqzvpys= Xref: csiph.com comp.lang.python:81922 On 04 Dec 2014 09:48:49 GMT albert@spenarnc.xs4all.nl (Albert van der Horst) wrote: > In article <546d7505$0$12899$c3e8da3$5496439d@news.astraweb.com>, > Steven D'Aprano wrote: > >And the award for the most gratuitous comments before an import goes to > >one of my (former) workmates, who wrote this piece of code: > > > ># Used for base64-decoding. > >import base64 > ># Used for ungzipping. > >import gzip > > The comment lines contain genuine information. The program is > decoding or gunzipping. (And apparently not doing the encoding part) > > This information may have been better conveyed by > " > from base64 import base64-decode > from gzip import gunzip > " > but anyway. > > Also the comment may be misleading, but I think not. > > If there are mysterious names for packages, the comment may be > actually useful. > " > # Auxiliary for the reverse recursion to calculate > # Chebychev coefficients. > import courseware-2014-ch11 > " > > A professor who demands from students that every import is documented > is IMO not to blame. > In a company's coding convention ... I've seen a lot of things there > that make a lot less sense. > > >-- > >Steven > -- > Albert van der Horst, UTRECHT,THE NETHERLANDS > Economic growth -- being exponential -- ultimately falters. > albert@spe&ar&c.xs4all.nl &=n http://home.hccnet.nl/a.w.m.van.der.horst > In my code, I habitually use big old bar comments to break the imports into three sections, standard library, third-party libraries, and local imports. I find it radically simplifies knowing where to start looking for documentation. -- Rob Gaddi, Highland Technology -- www.highlandtechnology.com Email address domain is currently out of order. See above to fix.