[Python-Dev] More Zen

[Michael Hudson]

"Raymond Hettinger" <raymond.hettinger@verizon.net> writes:

[snip stuff I agree with]

> 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

school of commenting.

Cheers,
M.

-- 
  Our lecture theatre has just crashed. It will currently only
  silently display an unexplained line-drawing of a large dog
  accompanied by spookily flickering lights.
     -- Dan Sheppard, ucam.chat (from Owen Dunn's summary of the year)