Iterators unified access to containers -- lets find more of those. Substitutability simplifies development so shelves have a full dictionary interface but tuples won't sprout a count method because lists differ in intent. Deprecation comes at a price but cruft has a cost of its own. Holistic refactoring beats piecemeal optimization. Comment generously, the best modules are an education to read. Be kind on the Usenet some posters are only eleven. Raymond Hettinger
"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)
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
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
participants (4)
-
Ken Manheimer -
Michael Hudson -
Raymond Hettinger -
Raymond Hettinger