The worth of comments

On May 26, 2011, at 4:28 AM, python-list-request@xxxxxxxxxx wrote:

My experience is that comments in Python are of relatively low
usefulness. (For avoidance of doubt: not *zero* usefulness, merely low.)
I can name variables, functions and classes with sensible, self-
documenting names. Why write:

x = get_results(arg) # x is a list of 1 or more results
[... much later]
for y in x:
# process each result in turn
do_something_with(y)

(It occurred to me that I should use a specific subject for this discussion.)

I'm less inclined to use comments on each line, or selected lines, but rather use block comments instead. They require more thought and time to write; however, the intended functionality of the code that follows can be described in full.

.

Relevant Pages

  • Re: The worth of comments
    ... (For avoidance of doubt: not *zero* usefulness, ... self- documenting names. ... I am largely in agreement with this position (including the “not *zero* ... helpfully-named function with its doc string having the explanation. ...
    (comp.lang.python)
  • Re: The worth of comments
    ... (For avoidance of doubt: not *zero* usefulness, ... documenting names. ...
    (comp.lang.python)
  • Re: The worth of comments
    ... (For avoidance of doubt: not *zero* usefulness, ... I've seen plenty of comments who's usefulness was not zero. ...
    (comp.lang.python)
  • Re: The worth of comments
    ... not *zero* usefulness, ... documenting names. ... now things like helpcan get at it, and things like doctest can do ... stuff, references to classic algorithms, references to ticket tracking ...
    (comp.lang.python)
  • Re: The worth of comments
    ... (For avoidance of doubt: not *zero* usefulness, ... I've seen plenty of comments who's usefulness was not zero. ... We're not a Python shop so I'm probably the only one reading this, ...
    (comp.lang.python)