Most gratuitous comments

[Rob Gaddi]

On 04 Dec 2014 09:48:49 GMT
albert at spenarnc.xs4all.nl (Albert van der Horst) wrote:

> In article <546d7505$0$12899$c3e8da3$5496439d at news.astraweb.com>,
> Steven D'Aprano  <steve at pearwood.info> 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 at 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.