[Python-Dev] More Zen (original) (raw)

Michael Hudson mwh@python.net
Thu, 06 Mar 2003 11:36:58 +0000

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