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

Groups > comp.lang.python > #6473

Re: The worth of comments

Show all headers | View raw

In article <irooea$kio$2@reader1.panix.com>,
 Grant Edwards <invalid@invalid.invalid> wrote:

> When trying to find a bug in code written by sombody else, I often
> first go through and delete all of the comments so as not to be
> mislead.

I've heard people say that before.  While I get the concept, I don't 
like doing things that way myself.

>> The comments reflect what the author _thought_ the code did
> _at_some_point_in_the_past_.  What matters is what the code actually
> does at the present.

I don't look at it that way.  Most of the comments I write are to 
document interfaces, i.e. what the code is supposed to do.  That's the 
contract between you and the code.  If you call me with arguments that 
meet these conditions, this is what I promise I'll return to you (and 
what side effects I'll perform).

One reasonable definition of a bug is something the code actually does 
which differs from the documented interface.  Unless you know what the 
code is supposed to do, how can you possibly look at it and say whether 
it has a bug or not?  For example, take this function:

def foo():
   l = [1, 2, 3]
   return l[3]

Is this code correct?  I'll bet most people would look at this and say, 
"I'm not sure what he had in mind, but whatever it was, this has to be a 
bug because he's indexing past the end of the list".  Well, what if I 
showed you the interface contract:

def foo():
   "Raise IndexError.  This is useful as a testing fixture."
   l = [1, 2, 3]
   return l[3]

Now it's obvious that the function does exactly what it's supposed to do 
(even if it's not the best way to do it).

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