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

Groups > comp.lang.python > #6547

Re: The worth of comments

Show all headers | View raw

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

> On 2011-05-29, Gregory Ewing <greg.ewing@canterbury.ac.nz> wrote:
> > Ben Finney wrote:
> >
> >> You omit the common third possibility: *both* the comment and the code
> >> are wrong.
> >
> > In that case, the correct response is to fix both of them. :-)
> 
> Only as a last resort. IMO, the best option is to fix the code so it's
> purpose and operation is obvious from the code, and then delete the
> comment.

This is a plausible(*) strategy for internal use software where all 
users have easy access to all code which depends on yours and are free 
to change interfaces willy-nilly.  That's not always the case.  Even on 
open-source projects, having stand-alone documentation is critical for 
usability, and certainly having stable interfaces is critical if you 
expect people to adopt your system and build on it.

(*)And, even in the case where it's internal code and everybody on the 
project has full and unfettered access to all the source, documenting 
interfaces adds to usability.  I've seen plenty of code which looks like 
this (pseudo-code):

Class1::f1() {
   return Class2::f2();
}

Class2::f2() {
   return Class3::f3();
}

Class3::f3() {
   return Class4::f4();
}

If you're trying to figure out what type of object f1() returns, you've 
got to chase down a long string of, "Well, f1 returns whatever f2 
returns, and f2 returns whatever f3 returns, and f3 returns whatever f4 
returns, and...."  Each step in that process might involve figuring out 
just where the heck the code for ClassN is.  And Cthulhu help you if 
some step along the way involves an indirectly referenced class or 
function so you can't even grep the source tree for the name you're 
looking for.

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