The worth of comments

[Grant Edwards]

On 2011-05-27, Ben Finney <ben+python at benfinney.id.au> wrote:
> 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've seen plenty of comments who's usefulness was not zero.  It was
less than zero.

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

I consider docstrings to be the same as comments, so there's not
really much disagreement.

-- 
Grant Edwards               grant.b.edwards        Yow! Am I in Milwaukee?
                                  at               
                              gmail.com