The worth of comments

[Ben Finney]

Richard Parker <r.richardparker at comcast.net> writes:

> On May 26, 2011, at 4:28 AM, python-list-request at python.org 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.

I am largely in agreement with this position (including the “not *zero*
usefulness” caveat).

> 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.

This I disagree with. If a section of code is interesting enough to
deserve an explanation, then it is better to capture it in a
helpfully-named function with its doc string having the explanation.

-- 
 \        “If this is your first visit to the USSR, you are welcome to |
  `\                                          it.” —hotel room, Moscow |
_o__)                                                                  |
Ben Finney