The worth of comments

[Roy Smith]

In article <mailman.2126.1306435826.9059.python-list at python.org>,
 Richard Parker <r.richardparker at comcast.net> wrote:

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

Over the years, my use of comments has evolved.  I was taught, "You 
should comment your code".  Eventually, I came to realize that the real 
mandate is, "You should make it easy to understand your code".  Comments 
are just one possible tool to help achieve that goal.

Some things that help code be understandable are:

* Using good data structures

* Using good algorithms

* Breaking the code up into manageable pieces (i.e. functions, classes, 
methods), each of which encapsulates a single concept

* Using descriptive names for variables (and functions, classes, 
methods, etc)

All of those fall under the "self-documenting code" umbrella.  But, 
while those things help, I find it's almost always a good idea to 
document interfaces, i.e. functions.  What the arguments are (not just 
their types, but valid value ranges, and what they mean).  What the 
function returns.  What error conditions are possible.  And, in general, 
what the dang thing does.  In other words, enough information to use 
(and test) the function to its fullest extent without ever having to 
look at the source code.  This stuff tends to go in a big block comment 
at the beginning of the function.

Now, what makes Python interesting in this regard is that the big block 
comment becomes a doc string.  You write exactly the same stuff, except 
now things like help() can get at it, and things like doctest can do 
even more interesting things with it (I don't actually use doctest, but 
I do appreciate its coolness).

Comments scattered throughout the code tend to be warnings about tricky 
stuff, references to classic algorithms, references to ticket tracking 
systems, and the like.  Sometimes it's an explanation of what the next 
bunch of lines of code are doing, although if you've got a lot of those, 
that's a hint that maybe you need to be refactoring instead.  Sometimes 
I'll drop in suggestions to future maintainers like, "consider 
refactoring with with perform_frobnitz_action()", or even, "Don't change 
this without first talking to Fred!"