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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4