Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #6361

Re: The worth of comments

Show all headers | View raw

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

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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

The worth of comments Richard Parker <r.richardparker@comcast.net> - 2011-05-26 11:50 -0700
  Re: The worth of comments Ben Finney <ben+python@benfinney.id.au> - 2011-05-27 11:42 +1000
    Re: The worth of comments Grant Edwards <invalid@invalid.invalid> - 2011-05-27 13:54 +0000
      Re: The worth of comments Irmen de Jong <irmen@-NOSPAM-xs4all.nl> - 2011-05-27 19:05 +0200
        Re: The worth of comments Grant Edwards <invalid@invalid.invalid> - 2011-05-27 17:53 +0000
          Re: The worth of comments Irmen de Jong <irmen.NOSPAM@xs4all.nl> - 2011-05-28 15:09 +0200
            Re: The worth of comments python@bdurham.com - 2011-05-28 09:34 -0400
          Re: The worth of comments Roy Smith <roy@panix.com> - 2011-05-28 09:36 -0400
            Re: The worth of comments Chris Angelico <rosuav@gmail.com> - 2011-05-29 00:02 +1000
            Re: The worth of comments Irmen de Jong <irmen.NOSPAM@xs4all.nl> - 2011-05-28 16:05 +0200
              Re: The worth of comments Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2011-05-29 12:47 +1200
                Re: The worth of comments Ben Finney <ben+python@benfinney.id.au> - 2011-05-29 11:41 +1000
                Re: The worth of comments Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2011-05-29 23:05 +1200
                Re: The worth of comments Grant Edwards <invalid@invalid.invalid> - 2011-05-29 14:43 +0000
                Re: The worth of comments Roy Smith <roy@panix.com> - 2011-05-29 11:39 -0400
                Re: The worth of comments Irmen de Jong <irmen.NOSPAM@xs4all.nl> - 2011-05-29 03:49 +0200
                Re: The worth of comments Alister Ware <alister.ware@ntlworld.com> - 2011-05-29 17:26 +0000
            Re: The worth of comments Neil Cerutti <neilc@norwich.edu> - 2011-05-31 14:47 +0000
  Re: The worth of comments Roy Smith <roy@panix.com> - 2011-05-26 22:08 -0400
    Re: The worth of comments Chris Angelico <rosuav@gmail.com> - 2011-05-27 15:13 +1000
      Re: The worth of comments Roy Smith <roy@panix.com> - 2011-05-27 09:25 -0400
    Re: The worth of comments Tim Roberts <timr@probo.com> - 2011-05-27 00:02 -0700
      Re: The worth of comments "D'Arcy J.M. Cain" <darcy@druid.net> - 2011-05-27 09:29 -0400
    RE: The worth of comments "Prasad, Ramit" <ramit.prasad@jpmchase.com> - 2011-05-27 14:17 -0400

csiph-web