[Python-Dev] More Zen

Raymond Hettinger python@rcn.com
Thu, 6 Mar 2003 10:52:22 -0500

From: "Michael Hudson" <mwh@python.net>
> > Comment generously, the best modules are an education to read.
> This one I have mild issues with.  Ideally, your code is so clear that
> it requires no comments to read!  And information for users of the
> code should be in docstrings.  If you're implementing a non-obvious
> algorithm then there's a place for a comment block educating the
> reader how it works, but I'm leery of anything that might seem to
> encourage the  "i = i + 1 # add one to i"

This ought to be more clear:

   Reading heapq and timeit makes you smart -- let's comment like that.

Raymond Hettinger