Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.python > #6336 > unrolled thread
| Started by | Richard Parker <r.richardparker@comcast.net> |
|---|---|
| First post | 2011-05-26 11:50 -0700 |
| Last post | 2011-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.
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 →
| From | Richard Parker <r.richardparker@comcast.net> |
|---|---|
| Date | 2011-05-26 11:50 -0700 |
| Subject | The 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]
| From | Ben Finney <ben+python@benfinney.id.au> |
|---|---|
| Date | 2011-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]
| From | Grant Edwards <invalid@invalid.invalid> |
|---|---|
| Date | 2011-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]
| From | Irmen de Jong <irmen@-NOSPAM-xs4all.nl> |
|---|---|
| Date | 2011-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]
| From | Grant Edwards <invalid@invalid.invalid> |
|---|---|
| Date | 2011-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]
| From | Irmen de Jong <irmen.NOSPAM@xs4all.nl> |
|---|---|
| Date | 2011-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]
| From | python@bdurham.com |
|---|---|
| Date | 2011-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]
| From | Roy Smith <roy@panix.com> |
|---|---|
| Date | 2011-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]
| From | Chris Angelico <rosuav@gmail.com> |
|---|---|
| Date | 2011-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]
| From | Irmen de Jong <irmen.NOSPAM@xs4all.nl> |
|---|---|
| Date | 2011-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]
| From | Gregory Ewing <greg.ewing@canterbury.ac.nz> |
|---|---|
| Date | 2011-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]
| From | Ben Finney <ben+python@benfinney.id.au> |
|---|---|
| Date | 2011-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]
| From | Gregory Ewing <greg.ewing@canterbury.ac.nz> |
|---|---|
| Date | 2011-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]
| From | Grant Edwards <invalid@invalid.invalid> |
|---|---|
| Date | 2011-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]
| From | Roy Smith <roy@panix.com> |
|---|---|
| Date | 2011-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]
| From | Irmen de Jong <irmen.NOSPAM@xs4all.nl> |
|---|---|
| Date | 2011-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]
| From | Alister Ware <alister.ware@ntlworld.com> |
|---|---|
| Date | 2011-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]
| From | Neil Cerutti <neilc@norwich.edu> |
|---|---|
| Date | 2011-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]
| From | Roy Smith <roy@panix.com> |
|---|---|
| Date | 2011-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]
| From | Chris Angelico <rosuav@gmail.com> |
|---|---|
| Date | 2011-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