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


Groups > comp.lang.python > #6336 > unrolled thread

The worth of comments

Started byRichard Parker <r.richardparker@comcast.net>
First post2011-05-26 11:50 -0700
Last post2011-05-27 14:17 -0400
Articles 20 on this page of 24 — 14 participants

Back to article view | Back to comp.lang.python

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.


Contents

  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

Page 1 of 2  [1] 2  Next page →


#6336 — The worth of comments

FromRichard Parker <r.richardparker@comcast.net>
Date2011-05-26 11:50 -0700
SubjectThe worth of comments
Message-ID<mailman.2126.1306435826.9059.python-list@python.org>
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.

[toc] | [next] | [standalone]


#6359

FromBen Finney <ben+python@benfinney.id.au>
Date2011-05-27 11:42 +1000
Message-ID<87sjs0apgh.fsf@benfinney.id.au>
In reply to#6336
Richard Parker <r.richardparker@comcast.net> writes:

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

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.

-- 
 \        “If this is your first visit to the USSR, you are welcome to |
  `\                                          it.” —hotel room, Moscow |
_o__)                                                                  |
Ben Finney

[toc] | [prev] | [next] | [standalone]


#6390

FromGrant Edwards <invalid@invalid.invalid>
Date2011-05-27 13:54 +0000
Message-ID<iroadr$3gj$1@reader1.panix.com>
In reply to#6359
On 2011-05-27, Ben Finney <ben+python@benfinney.id.au> wrote:
> Richard Parker <r.richardparker@comcast.net> writes:
>
>> 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'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            

[toc] | [prev] | [next] | [standalone]


#6413

FromIrmen de Jong <irmen@-NOSPAM-xs4all.nl>
Date2011-05-27 19:05 +0200
Message-ID<4ddfd9bf$0$49183$e4fe514c@news.xs4all.nl>
In reply to#6390
On 27-05-11 15:54, Grant Edwards wrote:
> On 2011-05-27, Ben Finney<ben+python@benfinney.id.au>  wrote:
>> Richard Parker<r.richardparker@comcast.net>  writes:
>>
>>> 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've seen plenty of comments who's usefulness was not zero.  It was
> less than zero.

Someone once taught me, "There is one thing worse than having no 
comments in the source code:  having incorrect (or 'lying') comments in 
the code."

Grant, I guess you hint at such comments?

Irmen.

[toc] | [prev] | [next] | [standalone]


#6416

FromGrant Edwards <invalid@invalid.invalid>
Date2011-05-27 17:53 +0000
Message-ID<irooea$kio$2@reader1.panix.com>
In reply to#6413
On 2011-05-27, Irmen de Jong <irmen@-NOSPAM-xs4all.nl> wrote:
> On 27-05-11 15:54, Grant Edwards wrote:
>> On 2011-05-27, Ben Finney<ben+python@benfinney.id.au>  wrote:
>>> Richard Parker<r.richardparker@comcast.net>  writes:
>>>
>>>> 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've seen plenty of comments who's usefulness was not zero.  It was
>> less than zero.
>
> Someone once taught me, "There is one thing worse than having no 
> comments in the source code: having incorrect (or 'lying') comments
> in the code."
>
> Grant, I guess you hint at such comments?

Yes.  :)

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.

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.

-- 
Grant Edwards               grant.b.edwards        Yow! ... If I had heart
                                  at               failure right now,
                              gmail.com            I couldn't be a more
                                                   fortunate man!!

[toc] | [prev] | [next] | [standalone]


#6469

FromIrmen de Jong <irmen.NOSPAM@xs4all.nl>
Date2011-05-28 15:09 +0200
Message-ID<4de0f420$0$49047$e4fe514c@news.xs4all.nl>
In reply to#6416
On 27-5-2011 19:53, Grant Edwards wrote:
> On 2011-05-27, Irmen de Jong <irmen@-NOSPAM-xs4all.nl> wrote:
>> On 27-05-11 15:54, Grant Edwards wrote:
>>> On 2011-05-27, Ben Finney<ben+python@benfinney.id.au>  wrote:
>>>> Richard Parker<r.richardparker@comcast.net>  writes:
>>>>
>>>>> 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've seen plenty of comments who's usefulness was not zero.  It was
>>> less than zero.
>>
>> Someone once taught me, "There is one thing worse than having no 
>> comments in the source code: having incorrect (or 'lying') comments
>> in the code."
>>
>> Grant, I guess you hint at such comments?
> 
> Yes.  :)
> 
> 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.
> 
> 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'm going to share this thread, and the funny slideshow about Uncomment your code, with
my team at work :-)
We're not a Python shop so I'm probably the only one reading this, but as usual there is
a lot of wisdom going on in this newgroup that is not only applicable to Python.

Irmen

[toc] | [prev] | [next] | [standalone]


#6471

Frompython@bdurham.com
Date2011-05-28 09:34 -0400
Message-ID<mailman.2193.1306589646.9059.python-list@python.org>
In reply to#6469
Irmen,

> I'm going to share this thread, and the funny slideshow about Uncomment your code, with my team at work :-) We're not a Python shop so I'm probably the only one reading this

Same here!

> but as usual there is a lot of wisdom going on in this new[s]group that is not only applicable to Python.

+1 QOTW

Malcolm

[toc] | [prev] | [next] | [standalone]


#6473

FromRoy Smith <roy@panix.com>
Date2011-05-28 09:36 -0400
Message-ID<roy-84AF4C.09364328052011@news.panix.com>
In reply to#6416
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).

[toc] | [prev] | [next] | [standalone]


#6476

FromChris Angelico <rosuav@gmail.com>
Date2011-05-29 00:02 +1000
Message-ID<mailman.2195.1306591380.9059.python-list@python.org>
In reply to#6473
On Sat, May 28, 2011 at 11:36 PM, Roy Smith <roy@panix.com> wrote:
> def foo():
>   "Raise IndexError.  This is useful as a testing fixture."
>   l = [1, 2, 3]
>   return l[3]

A quite useful thing, on occasion. I have a couple of variants of
this, actually. In one of my C++ programs:

extern char *death1; extern int death2; //Globals for killing things with

// further down, inside a function:
case "death1": *death1=42; break; //Die by dereferencing NULL
case "death2": return 42/death2; //Die by dividing by zero

They were designed to verify the parent-process code that was meant to
catch process termination and identify the cause, so I wanted two
quite different ways of blowing up the program. (The variables were
extern and defined in another file to ensure that the compiler
couldn't outsmart me with a compilation error.)

In the Python code, that would be unnecessary with the *list* type,
but it might be of value with your own class (eg subclass of list).
Although, I'd put that sort of thing into a dedicated unit testing
section, where everyone _knows_ that you're trying to break stuff.

Chris Angelico

[toc] | [prev] | [next] | [standalone]


#6478

FromIrmen de Jong <irmen.NOSPAM@xs4all.nl>
Date2011-05-28 16:05 +0200
Message-ID<4de1011f$0$49184$e4fe514c@news.xs4all.nl>
In reply to#6473
On 28-5-2011 15:36, Roy Smith wrote:
> 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).

I don't see how that is opposed to what Grant was saying. It's that these 'contracts'
tend to change and that people forget or are too lazy to update the comments to reflect
those changes.

The comments you are writing, saying what the code is supposed to do, are only saying
what the code is supposed to do at the moment in time that you were writing the comment
and/or the code, are they not?

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

Unit tests should tell you.


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

I do agree that reading just that piece of code without other information, makes me
think that it is fishy. But:


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

A month later the requirement changes: it should raise a ZeroDevisionError instead.
Someone modifies the code but leaves the comment (for whatever reason).

def foo():
    "Raise IndexError.  This is useful as a testing fixture."
    return 1//0

Unless there is a way to force people to update the code comment as well (which I'm not
aware of.. Doctests? dunno...),  you now have a comment that lies about the the intended
working.   In my opinion that is worse than what we had before (the function without
comment).


That being said, I do write code comments myself. Some of them are like notes, directed
to future-me or other future readers (remember that we do this because blabla, don't
change this to such-and-such because it will probably break xyz) and some of them are
stating the contract of the code (like you wrote above, about documenting interfaces).
I always try to avoid writing comments that duplicate the working of the code itself in
pseudo code or text phrases.  But humans make mistakes and forget things so after enough
modifications my code probably contains lies as well... :(


Irmen de Jong

[toc] | [prev] | [next] | [standalone]


#6504

FromGregory Ewing <greg.ewing@canterbury.ac.nz>
Date2011-05-29 12:47 +1200
Message-ID<94djdoFt6U1@mid.individual.net>
In reply to#6478
Irmen de Jong wrote:

> I don't see how that is opposed to what Grant was saying. It's that these 'contracts'
> tend to change and that people forget or are too lazy to update the comments to reflect
> those changes.

However, I can't see that deleting the comment documenting the
contract can be the right response to the situation.

If the contract comment doesn't match what code does, then
there are two possibilities -- the comment is wrong, or the
code is wrong. The appropriate response is to find out which
one is wrong and fix it.

If you simply delete the comment, then you're left with no
redundancy to catch the fact that something is wrong.

-- 
Greg

[toc] | [prev] | [next] | [standalone]


#6507

FromBen Finney <ben+python@benfinney.id.au>
Date2011-05-29 11:41 +1000
Message-ID<877h9a9tbb.fsf@benfinney.id.au>
In reply to#6504
Gregory Ewing <greg.ewing@canterbury.ac.nz> writes:

> If the contract comment doesn't match what code does, then there are
> two possibilities -- the comment is wrong, or the code is wrong. The
> appropriate response is to find out which one is wrong and fix it.

You omit the common third possibility: *both* the comment and the code
are wrong.

That's the one that I bet on whenever I notice code and comment don't
match.

-- 
 \     “Anyone can do any amount of work provided it isn't the work he |
  `\          is supposed to be doing at the moment.” —Robert Benchley |
_o__)                                                                  |
Ben Finney

[toc] | [prev] | [next] | [standalone]


#6527

FromGregory Ewing <greg.ewing@canterbury.ac.nz>
Date2011-05-29 23:05 +1200
Message-ID<94enkcFj5mU1@mid.individual.net>
In reply to#6507
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. :-)

-- 
Greg

[toc] | [prev] | [next] | [standalone]


#6544

FromGrant Edwards <invalid@invalid.invalid>
Date2011-05-29 14:43 +0000
Message-ID<irtm3d$qk3$2@reader1.panix.com>
In reply to#6527
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.

-- 
Grant


[toc] | [prev] | [next] | [standalone]


#6547

FromRoy Smith <roy@panix.com>
Date2011-05-29 11:39 -0400
Message-ID<roy-77BA3B.11391829052011@news.panix.com>
In reply to#6544
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.

[toc] | [prev] | [next] | [standalone]


#6508

FromIrmen de Jong <irmen.NOSPAM@xs4all.nl>
Date2011-05-29 03:49 +0200
Message-ID<4de1a624$0$49178$e4fe514c@news.xs4all.nl>
In reply to#6504
On 29-5-2011 2:47, Gregory Ewing wrote:
> Irmen de Jong wrote:
> 
>> I don't see how that is opposed to what Grant was saying. It's that these 'contracts'
>> tend to change and that people forget or are too lazy to update the comments to reflect
>> those changes.
> 
> However, I can't see that deleting the comment documenting the
> contract can be the right response to the situation.
> 
> If the contract comment doesn't match what code does, then
> there are two possibilities -- the comment is wrong, or the
> code is wrong. The appropriate response is to find out which
> one is wrong and fix it.

Fair enough.

Certainly I won't be deleting every source code comment encountered from now on, but I
do think we should keep in mind the risks already mentioned. In some situations I can
very well imagine it is best to simply delete any comments and go with just the code.


> If you simply delete the comment, then you're left with no
> redundancy to catch the fact that something is wrong.

You are right, if you don't have a Unit test for it.
Then again, faulty unit tests are a problem in their own right...

Irmen de Jong

[toc] | [prev] | [next] | [standalone]


#6552

FromAlister Ware <alister.ware@ntlworld.com>
Date2011-05-29 17:26 +0000
Message-ID<YkvEp.32065$yI6.10816@newsfe06.ams2>
In reply to#6504
On Sun, 29 May 2011 12:47:52 +1200, Gregory Ewing wrote:

> Irmen de Jong wrote:
> 
>> I don't see how that is opposed to what Grant was saying. It's that
>> these 'contracts' tend to change and that people forget or are too lazy
>> to update the comments to reflect those changes.
> 
> However, I can't see that deleting the comment documenting the contract
> can be the right response to the situation.
> 
> If the contract comment doesn't match what code does, then there are two
> possibilities -- the comment is wrong, or the code is wrong. The
> appropriate response is to find out which one is wrong and fix it.
> 
> If you simply delete the comment, then you're left with no redundancy to
> catch the fact that something is wrong.

"if the comments & code disagree then both are probably wrong"



-- 
Most public domain software is free, at least at first glance.

[toc] | [prev] | [next] | [standalone]


#6731

FromNeil Cerutti <neilc@norwich.edu>
Date2011-05-31 14:47 +0000
Message-ID<94kdbmFi80U2@mid.individual.net>
In reply to#6473
On 2011-05-28, Roy Smith <roy@panix.com> wrote:
> 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).

That's an excellent illustration of bad code hid by a bad comment.

Perhaps better:

def foo():
  raise IndexError()

-- 
Neil Cerutti

[toc] | [prev] | [next] | [standalone]


#6361

FromRoy Smith <roy@panix.com>
Date2011-05-26 22:08 -0400
Message-ID<roy-6F4F8A.22082526052011@news.panix.com>
In reply to#6336
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!"

[toc] | [prev] | [next] | [standalone]


#6371

FromChris Angelico <rosuav@gmail.com>
Date2011-05-27 15:13 +1000
Message-ID<mailman.2145.1306473197.9059.python-list@python.org>
In reply to#6361
On Fri, May 27, 2011 at 12:08 PM, Roy Smith <roy@panix.com> wrote:
>  Sometimes
> I'll drop in suggestions to future maintainers like, "consider
> refactoring with with perform_frobnitz_action()"

Usually, I address future-me with comments like that (on the
assumption that there's nobody in the world sadistic enough to want to
maintain my code). But I never name future-me, the comments will be
addressed to "the subsequent maintainer" or somesuch. I do assume,
though, that future-me has forgotten everything about the code, and
since past-me left some comments that current-me has read, I think the
assumption is fairly accurate. (Did I *really* write that code? It has
my name on it.....)

Chris Angelico

[toc] | [prev] | [next] | [standalone]


Page 1 of 2  [1] 2  Next page →

Back to top | Article view | comp.lang.python


csiph-web