[Python-Dev] More Zen

[Ken Manheimer]

On Thu, 6 Mar 2003, Michael Hudson wrote:

> "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.

I expect that _sometimes_ some code cannot be clear, even on occasions
when the algorithm is not, as a whole, particularly abstruse.  I
agree, though, that unnecessary comments are harmful.  How about
framing it like this:

  Comment obscure code, let the obvious speak for itself.

-- 
Ken
klm@zope.com