[Python-Dev] More Zen
Thu, 6 Mar 2003 12:15:09 -0500 (EST)
On Thu, 6 Mar 2003, Michael Hudson wrote:
> "Raymond Hettinger" <firstname.lastname@example.org> 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.