FAQ

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

Search Discussions

  • Patty at May 26, 2011 at 8:30 pm
    ----- Original Message -----
    From: "Richard Parker" <r.richardparker at comcast.net>
    To: <python-list at python.org>
    Sent: Thursday, May 26, 2011 11:50 AM
    Subject: The worth of comments

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

    --
    http://mail.python.org/mailman/listinfo/python-list
    Hello Richard - I was recently complimented in a phone screen interview for
    including comment blocks exactly as you describe above.

    Regards,

    Patty
  • Ben Finney at May 27, 2011 at 1:42 am

    Richard Parker <r.richardparker at comcast.net> writes:
    On May 26, 2011, at 4:28 AM, python-list-request at 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
  • Grant Edwards at May 27, 2011 at 1:54 pm

    On 2011-05-27, Ben Finney wrote:
    Richard Parker <r.richardparker at comcast.net> writes:
    On May 26, 2011, at 4:28 AM, python-list-request at 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
  • Irmen de Jong at May 27, 2011 at 5:05 pm

    On 27-05-11 15:54, Grant Edwards wrote:
    On 2011-05-27, Ben Finneywrote:
    Richard Parker<r.richardparker at comcast.net> writes:
    On May 26, 2011, at 4:28 AM, python-list-request at 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.
  • Grant Edwards at May 27, 2011 at 5:53 pm

    On 2011-05-27, Irmen de Jong wrote:
    On 27-05-11 15:54, Grant Edwards wrote:
    On 2011-05-27, Ben Finneywrote:
    Richard Parker<r.richardparker at comcast.net> writes:
    On May 26, 2011, at 4:28 AM, python-list-request at 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!!
  • Irmen de Jong at May 28, 2011 at 1:09 pm

    On 27-5-2011 19:53, Grant Edwards wrote:
    On 2011-05-27, Irmen de Jong wrote:
    On 27-05-11 15:54, Grant Edwards wrote:
    On 2011-05-27, Ben Finneywrote:
    Richard Parker<r.richardparker at comcast.net> writes:
    On May 26, 2011, at 4:28 AM, python-list-request at 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
  • Python at May 28, 2011 at 1:34 pm
    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
  • Roy Smith at May 28, 2011 at 1:36 pm
    In article <irooea$kio$2 at reader1.panix.com>,
    Grant Edwards 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).
  • Chris Angelico at May 28, 2011 at 2:02 pm

    On Sat, May 28, 2011 at 11:36 PM, Roy Smith 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": *death1B; 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
  • Irmen de Jong at May 28, 2011 at 2:05 pm

    On 28-5-2011 15:36, Roy Smith wrote:
    In article <irooea$kio$2 at reader1.panix.com>,
    Grant Edwards 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
  • Gregory Ewing at May 29, 2011 at 12:47 am

    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
  • Ben Finney at May 29, 2011 at 1:41 am

    Gregory Ewing <greg.ewing at 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
  • Gregory Ewing at May 29, 2011 at 11:05 am

    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
  • Grant Edwards at May 29, 2011 at 2:43 pm

    On 2011-05-29, Gregory Ewing 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
  • Roy Smith at May 29, 2011 at 3:39 pm
    In article <irtm3d$qk3$2 at reader1.panix.com>,
    Grant Edwards wrote:
    On 2011-05-29, Gregory Ewing 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.
  • Irmen de Jong at May 29, 2011 at 1:49 am

    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
  • Alister Ware at May 29, 2011 at 5:26 pm

    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.
  • Neil Cerutti at May 31, 2011 at 2:47 pm

    On 2011-05-28, Roy Smith 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
  • Roy Smith at May 27, 2011 at 2:08 am
    In article <mailman.2126.1306435826.9059.python-list at python.org>,
    Richard Parker wrote:
    On May 26, 2011, at 4:28 AM, python-list-request at 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!"
  • Chris Angelico at May 27, 2011 at 5:13 am

    On Fri, May 27, 2011 at 12:08 PM, Roy Smith 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
  • Prasad, Ramit at May 27, 2011 at 6:17 pm
    (Did I *really* write that code? It has my name on it.....)
    Damn those ninja programmers who stole your name and coded something!


    Ramit



    Ramit Prasad | JPMorgan Chase Investment Bank | Currencies Technology
    712 Main Street | Houston, TX 77002
    work phone: 713 - 216 - 5423



    This communication is for informational purposes only. It is not
    intended as an offer or solicitation for the purchase or sale of
    any financial instrument or as an official confirmation of any
    transaction. All market prices, data and other information are not
    warranted as to completeness or accuracy and are subject to change
    without notice. Any comments or statements made herein do not
    necessarily reflect those of JPMorgan Chase & Co., its subsidiaries
    and affiliates.

    This transmission may contain information that is privileged,
    confidential, legally privileged, and/or exempt from disclosure
    under applicable law. If you are not the intended recipient, you
    are hereby notified that any disclosure, copying, distribution, or
    use of the information contained herein (including any reliance
    thereon) is STRICTLY PROHIBITED. Although this transmission and any
    attachments are believed to be free of any virus or other defect
    that might affect any computer system into which it is received and
    opened, it is the responsibility of the recipient to ensure that it
    is virus free and no responsibility is accepted by JPMorgan Chase &
    Co., its subsidiaries and affiliates, as applicable, for any loss
    or damage arising in any way from its use. If you received this
    transmission in error, please immediately contact the sender and
    destroy the material in its entirety, whether in electronic or hard
    copy format. Thank you.

    Please refer to http://www.jpmorgan.com/pages/disclosures for
    disclosures relating to European legal entities.
  • Tim Roberts at May 27, 2011 at 7:02 am

    Roy Smith wrote:
    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.
    Absolutely correct. In my view, this is one of the strongest attributes of
    Python -- its syntax is such that much of the code can be read out loud
    like prose. That's a HUGE benefit. Code is read a lot more often than it
    is written.

    Ruby has a lot of followers, and I am trying to get excited about it, but
    it has succumbed to the same special-characters-as-syntax disease that
    killed Perl. Much Ruby code is just unreadable.
    --
    Tim Roberts, timr at probo.com
    Providenza & Boekelheide, Inc.
  • D'Arcy J.M. Cain at May 27, 2011 at 1:29 pm

    On Fri, 27 May 2011 00:02:23 -0700 Tim Roberts wrote:
    Ruby has a lot of followers, and I am trying to get excited about it, but
    it has succumbed to the same special-characters-as-syntax disease that
    killed Perl. Much Ruby code is just unreadable.
    What? The recent Perl flame war wasn't enough entertainment for
    you? ;-)

    --
    D'Arcy J.M. Cain <darcy at druid.net> | Democracy is three wolves
    http://www.druid.net/darcy/ | and a sheep voting on
    +1 416 425 1212 (DoD#0082) (eNTP) | what's for dinner.
  • Roy Smith at May 27, 2011 at 1:25 pm
    In article <mailman.2145.1306473197.9059.python-list at python.org>,
    Chris Angelico wrote:
    (Did I *really* write that code? It has my name on it.....)
    Most version control systems have an annotate command which lets you see
    who wrote a given line of code. Some of them are even honest enough to
    call the command "blame" instead of "annotate" :-)

    And, yes, it's always a rude shock when I stare at some hunk of code,
    mutter, "who wrote this crap!?" and fire up annotate/blame only to
    discover my name on it.
  • Miki Tebeka at May 27, 2011 at 3:57 pm
  • Ethan Furman at May 27, 2011 at 6:14 pm

    +1

    That was hilarious.

    ~Ethan~
  • Patty at May 27, 2011 at 6:21 pm
    ----- Original Message -----
    From: "Ethan Furman" <ethan at stoneleaf.us>
    To: <python-list at python.org>
    Sent: Friday, May 27, 2011 11:14 AM
    Subject: Re: The worth of comments

    I know - since I am not working right now, it totally made me wonder why I
    put comments in
    Python code at all -- or even have anything to do with code -- and plans
    being made to spend
    the rest of the day laying around in the hammock :)

    Patty
  • Grant Edwards at May 27, 2011 at 5:49 pm

    I just realized that Usenet is sort of like radio.

    After hearing/reading somebody for years, I don't seem to have a
    detailed image of them in my head, but when I finally do see a picture
    of them, my initial reaction is almost always "no, that's not at all
    what I thought he/she looked like". Odd.

    --
    Grant Edwards grant.b.edwards Yow! I demand IMPUNITY!
    at
    gmail.com
  • Gregory Ewing at May 28, 2011 at 8:30 am

    Grant Edwards wrote:

    After hearing/reading somebody for years, I don't seem to have a
    detailed image of them in my head, but when I finally do see a picture
    of them, my initial reaction is almost always "no, that's not at all
    what I thought he/she looked like".
    It works the other way, too. I've known what Terry Pratchett looks
    like for many years from the pictures on his books. When I heard
    him on the radio for the first time recently, I thought, "Wait
    a minute, that's not what his voice is supposed to sound like!"

    --
    Greg

Related Discussions

People

Translate

site design / logo © 2022 Grokbase