Docstrings considered too complicated

Discussion in 'Python' started by Andreas Waldenburger, Feb 24, 2010.

  1. Hi all,

    a company that works with my company writes a lot of of their code in
    Python (lucky jerks). I've seen their code and it basically looks like
    this:

    """Function that does stuff"""
    def doStuff():
    while not wise(up):
    yield scorn

    Now my question is this: How do I kill these people without the
    authorities thinking they didn't deserve it?

    /W

    --
    INVALID? DE!
     
    Andreas Waldenburger, Feb 24, 2010
    #1
    1. Advertising

  2. On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger
    <> wrote:
    > Hi all,
    >
    > a company that works with my company writes a lot of of their code in
    > Python (lucky jerks). I've seen their code and it basically looks like
    > this:
    >
    > """Function that does stuff"""
    > def doStuff():
    >    while not wise(up):
    >        yield scorn
    >
    > Now my question is this: How do I kill these people without the
    > authorities thinking they didn't deserve it?
    >


    kill -9 seems to work for me.

    You may want to explain, one day, why what they are doing is wrong.

    --
    Jonathan Gardner
     
    Jonathan Gardner, Feb 24, 2010
    #2
    1. Advertising

  3. Andreas Waldenburger

    John Posner Guest

    On 2/24/2010 4:54 PM, Jonathan Gardner wrote:
    > On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger
    > <> wrote:
    >> Hi all,
    >>
    >> a company that works with my company writes a lot of of their code in
    >> Python (lucky jerks). I've seen their code and it basically looks like
    >> this:
    >>
    >> """Function that does stuff"""
    >> def doStuff():
    >> while not wise(up):
    >> yield scorn
    >>
    >> Now my question is this: How do I kill these people without the
    >> authorities thinking they didn't deserve it?
    >>

    >
    > kill -9 seems to work for me.
    >
    > You may want to explain, one day, why what they are doing is wrong.
    >


    They are thinking in JavaDoc, not Python.

    #------------------------------
    """Function that does stuff"""
    def doStuff():
    while not wise(up):
    yield scorn


    def doOtherStuff():
    """Function that does stuff"""
    while wise(up):
    yield joy

    print doStuff.__doc__
    print doOtherStuff.__doc__
    #------------------------------

    program output:

    None
    Function that does stuff

    -John
     
    John Posner, Feb 25, 2010
    #3
  4. On Wed, 24 Feb 2010 21:23:03 +0100, Andreas Waldenburger wrote:

    > Hi all,
    >
    > a company that works with my company writes a lot of of their code in
    > Python (lucky jerks). I've seen their code and it basically looks like
    > this:
    >
    > """Function that does stuff"""
    > def doStuff():
    > while not wise(up):
    > yield scorn
    >
    > Now my question is this: How do I kill these people without the
    > authorities thinking they didn't deserve it?



    Well, the above isn't *wrong* as such, it is equivalent to:


    # Function that does stuff
    def doStuff():
    while not wise(up):
    yield scorn


    which means the biggest problem is that they had the perfect opportunity
    to create a useful docstring and instead f***ed it up by turning it into
    a useless comment.

    The best way to teach them better is to introduce them to the joys of
    help(doStuff) and doctests.




    --
    Steven
     
    Steven D'Aprano, Feb 25, 2010
    #4
  5. Andreas Waldenburger

    Roy Smith Guest

    In article <>,
    Steven D'Aprano <> wrote:

    > # Function that does stuff
    > def doStuff():
    > while not wise(up):
    > yield scorn
    >
    >
    > which means the biggest problem is that they had the perfect opportunity
    > to create a useful docstring and instead f***ed it up by turning it into
    > a useless comment.
    >
    > The best way to teach them better is to introduce them to the joys of
    > help(doStuff) and doctests.


    Try the ROI (Return On Investment) argument.

    A programmer costs $X per hour (at first blush, take their salary, multiply
    by 1.5 for indirect costs, and divide by 2000 working hours per year). It
    took them N minutes to write that text, so now you know how much that piece
    of text cost in dollars.

    Given that you've invested that money, what's the best way to maximize your
    ROI? Well, you could take that text, and put it in front of the 'def'
    line. The ROI in that you can read the text when you view the source code.
    Perhaps by printing it out on green-bar, or carving it into clay tablets
    with a pointed stick.

    Or, you could put it after the 'def' line. Now, you can still read it when
    viewing the source file. But, you can also access it with help(). Or by
    getting the functions __doc__ string. Three times the ROI! Even the most
    pointy-haired bean counter can grok the fullness of that.
     
    Roy Smith, Feb 25, 2010
    #5
  6. On Wed, Feb 24, 2010 at 4:54 PM, Jonathan Gardner
    <> wrote:
    > On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger
    > <> wrote:
    >>
    >> Now my question is this: How do I kill these people without the
    >> authorities thinking they didn't deserve it?
    >>

    >
    > kill -9 seems to work for me.


    kill -1 -1

    Back in the days of thin X terminals I used that one as a quicker
    alternative to actually logging out. It is also useful if you start a
    fork bunny and need to hit the panic switch before the machine grinds
    to a halt.

    -Jack
     
    Jack Diederich, Feb 25, 2010
    #6
  7. Andreas Waldenburger

    John Roth Guest

    On Feb 24, 1:23 pm, Andreas Waldenburger <>
    wrote:
    > Hi all,
    >
    > a company that works with my company writes a lot of of their code in
    > Python (lucky jerks). I've seen their code and it basically looks like
    > this:
    >
    > """Function that does stuff"""
    > def doStuff():
    >     while not wise(up):
    >         yield scorn
    >
    > Now my question is this: How do I kill these people without the
    > authorities thinking they didn't deserve it?
    >
    > /W
    >
    > --
    > INVALID? DE!


    Is the problem that they've got the docstring in the wrong place,
    or that the comment isn't saying anything that can't be read in
    the method name?

    The first is easily fixable with a bit of tutorial about how
    a properly placed docstring prints out in various contexts, plus
    a quick script to move the suckers.

    The second is going to take more work to get the point across
    that comments that reproduce what the method name says are waste.

    John Roth
     
    John Roth, Feb 25, 2010
    #7
  8. On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth
    <> wrote:

    > On Feb 24, 1:23 pm, Andreas Waldenburger <>
    > wrote:
    > > a company that works with my company writes a lot of of their code
    > > in Python (lucky jerks). I've seen their code and it basically
    > > looks like this:
    > >
    > > """Function that does stuff"""
    > > def doStuff():
    > >     while not wise(up):
    > >         yield scorn
    > > [snip]

    > Is the problem that they've got the docstring in the wrong place,
    > or that the comment isn't saying anything that can't be read in
    > the method name?
    >

    It's the first. I am superficial like that. I just needed a docstring
    to illustrate and didn't want to get overly creative.

    Not that they don't write redundant docstrings.

    And they use mixedCase function/method names.

    And they write getters and setters gratuitously.


    > The first is easily fixable with a bit of tutorial about how
    > a properly placed docstring prints out in various contexts, plus
    > a quick script to move the suckers.
    >

    Well, I'm not really in a position to tell them that. I'd be kind of
    the dork of the office in doing so. Thus my kvetching here. :)

    So basically, there is nothing to discuss, really. I just wanted to
    remind everyone that there are still morons out there (as in "lacking
    esprit and mental flexibility"), make everyone feel better about
    themselves (because surely THEY don't do that!) and then carry on.


    > The second is going to take more work to get the point across
    > that comments that reproduce what the method name says are waste.
    >

    They seem to need the reassurance, I guess, so why not let them. ;)

    /W


    --
    INVALID? DE!
     
    Andreas Waldenburger, Feb 26, 2010
    #8
  9. Andreas Waldenburger wrote:
    > On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth
    > <> wrote:
    >
    >
    >> On Feb 24, 1:23 pm, Andreas Waldenburger <>
    >> wrote:
    >>
    >>> a company that works with my company writes a lot of of their code
    >>> in Python (lucky jerks). I've seen their code and it basically
    >>> looks like this:
    >>>
    >>> """Function that does stuff"""
    >>> def doStuff():
    >>> while not wise(up):
    >>> yield scorn
    >>> [snip]
    >>>

    >> Is the problem that they've got the docstring in the wrong place,
    >> or that the comment isn't saying anything that can't be read in
    >> the method name?
    >>
    >>

    > It's the first. I am superficial like that. I just needed a docstring
    > to illustrate and didn't want to get overly creative.
    >
    > Not that they don't write redundant docstrings.
    >
    > And they use mixedCase function/method names.
    >

    and ? whatIsTheProblem ?
    PEP8 is one style guide, not *the* style guide. There is neither
    technical nor readability issue with mixedCase, classes in PEP 8 using
    MixedCase. The thing is they had to chose one preference for the methods
    and they choose lower_case. Fine, but it's still a matter of preference
    (or arbitrary decision). Since you don't write code for the standard
    library, you can use any other naming convention.
    You've may have guessed it, I am using mixedCase method names, and I
    tell you, you cannot compare this in any way with their dumb usage of
    doctrings you've shown above.

    That being said, yoru OP's still soemhow funny, I would have shot them
    on sight :)

    JM
     
    Jean-Michel Pichavant, Feb 26, 2010
    #9
  10. Andreas Waldenburger

    Tim Daneliuk Guest

    On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
    > Hi all,
    >
    > a company that works with my company writes a lot of of their code in
    > Python (lucky jerks). I've seen their code and it basically looks like
    > this:
    >
    > """Function that does stuff"""
    > def doStuff():
    > while not wise(up):
    > yield scorn
    >
    > Now my question is this: How do I kill these people without the
    > authorities thinking they didn't deserve it?
    >
    > /W
    >


    Reminiscent of:

    mov AX,BX ; Move the contents of BX into AX

    And, yes, I've actually seen that as well as:

    ; This is a comment



    --
    ----------------------------------------------------------------------------
    Tim Daneliuk
    PGP Key: http://www.tundraware.com/PGP/
     
    Tim Daneliuk, Feb 26, 2010
    #10
  11. On Fri, 26 Feb 2010 15:50:25 +0100 Jean-Michel Pichavant
    <> wrote:

    > Andreas Waldenburger wrote:
    >
    > > And they use mixedCase function/method names.
    > >

    > and ? whatIsTheProblem ?


    Thanks for proving my point. ;)

    No seriously though: Let it go. I wasn't being serious. As long as it
    works and I don't have to work with it, I don't care how anybody writes
    their code.

    /W

    --
    INVALID? DE!
     
    Andreas Waldenburger, Feb 26, 2010
    #11
  12. On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk <>
    wrote:

    > On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
    > > [stuff]

    >
    > Reminiscent of:
    >
    > mov AX,BX ; Move the contents of BX into AX
    >

    Well, there might be some confusion there as to what gets moved where,
    wouldn't you say? I guess this goes away after a couple of months,
    though.

    > And, yes, I've actually seen that as well as:
    >
    > ; This is a comment
    >

    I hope it was in a tutorial-situation. Or maybe it was written by one of
    those "ironic" programmers?

    /W

    --
    INVALID? DE!
     
    Andreas Waldenburger, Feb 26, 2010
    #12
  13. Andreas Waldenburger

    Roy Smith Guest

    In article <>,
    Tim Daneliuk <> wrote:

    > On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
    > > Hi all,
    > >
    > > a company that works with my company writes a lot of of their code in
    > > Python (lucky jerks). I've seen their code and it basically looks like
    > > this:
    > >
    > > """Function that does stuff"""
    > > def doStuff():
    > > while not wise(up):
    > > yield scorn
    > >
    > > Now my question is this: How do I kill these people without the
    > > authorities thinking they didn't deserve it?
    > >
    > > /W
    > >

    >
    > Reminiscent of:
    >
    > mov AX,BX ; Move the contents of BX into AX
    >
    > And, yes, I've actually seen that as well as:
    >
    > ; This is a comment


    OK, if we're going to do this, how about this one, that I just found
    yesterday in some production C++ code. I'm so glad somebody took the time
    to explain to me what p7 through p9 are. I never would have figured it out
    otherwise.

    /**
    * Tracing facility. Writes the message to the specified output stream.
    * If output stream is NULL, writes the message to the process log.
    *
    * @param msg_id The message id to use for lookup.
    * @param ostr The output stream.
    * @param p1 The first substition parameter.
    * @param p2 The second substition parameter.
    * @param p3 The third substition parameter.
    * @param p4 The fourth substition parameter.
    * @param p5 The fifth substition parameter.
    * @param p6 The sixth substition parameter.
    * @param p7 The seventh substition parameter.
    * @param p8 The eigth substition parameter.
    * @param p9 The ninth substition parameter.
    */
     
    Roy Smith, Feb 26, 2010
    #13
  14. Andreas Waldenburger

    Phlip Guest

    Andreas Waldenburger wrote:

    > """Function that does stuff"""
    > def doStuff():
    >     while not wise(up):
    >         yield scorn
    >
    > Now my question is this: How do I kill these people without the
    > authorities thinking they didn't deserve it?


    Their unit tests are just as complete, illustrative, and
    administratively sanctioned, right?

    --
    Phlip
    http://penbird.tumblr.com/
     
    Phlip, Feb 26, 2010
    #14
  15. "Andreas Waldenburger" <> wrote in message
    news:...

    >> Reminiscent of:
    >>
    >> mov AX,BX ; Move the contents of BX into AX
    >>

    > Well, there might be some confusion there as to what gets moved where,
    > wouldn't you say?


    Depends on what assembler you're used to. I certainly find having the
    operands that way round confusing.
     
    Richard Brodie, Feb 26, 2010
    #15
  16. Andreas Waldenburger wrote:
    > On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk <>
    > wrote:
    >
    >
    >> On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
    >>
    >>> [stuff]
    >>>

    >> Reminiscent of:
    >>
    >> mov AX,BX ; Move the contents of BX into AX
    >>
    >>

    > Well, there might be some confusion there as to what gets moved where,
    > wouldn't you say? I guess this goes away after a couple of months,
    > though.
    >


    I agree to that statement, I was surprised that mov AX,BX assumes that
    BX is the source, and AX the destination. I never programmed in
    assembler though.

    JM
     
    Jean-Michel Pichavant, Feb 26, 2010
    #16
  17. Roy Smith wrote:
    > In article <>,
    > Tim Daneliuk <> wrote:
    >
    >
    >> On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
    >>
    >>> Hi all,
    >>>
    >>> a company that works with my company writes a lot of of their code in
    >>> Python (lucky jerks). I've seen their code and it basically looks like
    >>> this:
    >>>
    >>> """Function that does stuff"""
    >>> def doStuff():
    >>> while not wise(up):
    >>> yield scorn
    >>>
    >>> Now my question is this: How do I kill these people without the
    >>> authorities thinking they didn't deserve it?
    >>>
    >>> /W
    >>>
    >>>

    >> Reminiscent of:
    >>
    >> mov AX,BX ; Move the contents of BX into AX
    >>
    >> And, yes, I've actually seen that as well as:
    >>
    >> ; This is a comment
    >>

    >
    > OK, if we're going to do this, how about this one, that I just found
    > yesterday in some production C++ code. I'm so glad somebody took the time
    > to explain to me what p7 through p9 are. I never would have figured it out
    > otherwise.
    >
    > /**
    > * Tracing facility. Writes the message to the specified output stream.
    > * If output stream is NULL, writes the message to the process log.
    > *
    > * @param msg_id The message id to use for lookup.
    > * @param ostr The output stream.
    > * @param p1 The first substition parameter.
    > * @param p2 The second substition parameter.
    > * @param p3 The third substition parameter.
    > * @param p4 The fourth substition parameter.
    > * @param p5 The fifth substition parameter.
    > * @param p6 The sixth substition parameter.
    > * @param p7 The seventh substition parameter.
    > * @param p8 The eigth substition parameter.
    > * @param p9 The ninth substition parameter.
    > */
    >

    just in case the first sub param would be p0 :)


    JM
     
    Jean-Michel Pichavant, Feb 26, 2010
    #17
  18. Andreas Waldenburger

    mk Guest

    Roy Smith wrote:

    > /**
    > * Tracing facility. Writes the message to the specified output stream.
    > * If output stream is NULL, writes the message to the process log.
    > *
    > * @param msg_id The message id to use for lookup.
    > * @param ostr The output stream.
    > * @param p1 The first substition parameter.
    > * @param p2 The second substition parameter.
    > * @param p3 The third substition parameter.
    > * @param p4 The fourth substition parameter.
    > * @param p5 The fifth substition parameter.
    > * @param p6 The sixth substition parameter.
    > * @param p7 The seventh substition parameter.
    > * @param p8 The eigth substition parameter.
    > * @param p9 The ninth substition parameter.
    > */


    Well at least they did explain something. ;-) You should be happy you
    don't have to deal with PHP programmers that tend to write
    20-positional-argument function AND programmer 1 knows what params 1-7
    do, programmer 2 knows what params 8-15 do and nobody knows what params
    16-20 do.

    Seriously.

    Regards,
    mk
     
    mk, Feb 26, 2010
    #18
  19. Andreas Waldenburger

    Mel Guest

    Jean-Michel Pichavant wrote:
    > Andreas Waldenburger wrote:
    >> On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk <>
    >> wrote:
    >>> Reminiscent of:
    >>> mov AX,BX ; Move the contents of BX into AX


    >> Well, there might be some confusion there as to what gets moved where,
    >> wouldn't you say? I guess this goes away after a couple of months,
    >> though.


    > I agree to that statement, I was surprised that mov AX,BX assumes that
    > BX is the source, and AX the destination. I never programmed in
    > assembler though.


    You could think of it as a not bad use of the design principle "Clear The
    Simple Stuff Out Of The Way First". Destinations are commonly a lot simpler
    than sources -- just as in Python assignment statements. So you can tell
    more or less at a glance what's going to be changed, then get into the deep
    analysis to find what it's going to be changed to.

    Mel.
     
    Mel, Feb 26, 2010
    #19
  20. On 2010-02-26, Jean-Michel Pichavant <> wrote:
    > Andreas Waldenburger wrote:
    >> On Fri, 26 Feb 2010 09:09:36 -0600 Tim Daneliuk <>
    >> wrote:
    >>
    >>
    >>> On 2/24/2010 2:23 PM, Andreas Waldenburger wrote:
    >>>
    >>>> [stuff]
    >>>>
    >>> Reminiscent of:
    >>>
    >>> mov AX,BX ; Move the contents of BX into AX

    >>
    >> Well, there might be some confusion there as to what gets moved where,
    >> wouldn't you say? I guess this goes away after a couple of months,
    >> though.

    >
    > I agree to that statement, I was surprised that mov AX,BX assumes that
    > BX is the source, and AX the destination. I never programmed in
    > assembler though.


    It depends on the assembler. Some are dst, src and others are
    the other way around. Some vary depending on the instruction.

    --
    Grant Edwards grante Yow! Sign my PETITION.
    at
    visi.com
     
    Grant Edwards, Feb 26, 2010
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Davmagic .Com

    CSS2 Way Too Complicated

    Davmagic .Com, Jul 14, 2004, in forum: HTML
    Replies:
    27
    Views:
    945
    Joel Shepherd
    Jul 16, 2004
  2. Smidak

    Re: CSS2 Way Too Complicated

    Smidak, Jul 15, 2004, in forum: HTML
    Replies:
    11
    Views:
    697
  3. Mark Parnell

    Re: CSS2 Way Too Complicated

    Mark Parnell, Jul 17, 2004, in forum: HTML
    Replies:
    0
    Views:
    384
    Mark Parnell
    Jul 17, 2004
  4. Mark Parnell

    Re: CSS2 Way Too Complicated

    Mark Parnell, Jul 17, 2004, in forum: HTML
    Replies:
    1
    Views:
    403
  5. mk
    Replies:
    2
    Views:
    251
    David Robinow
    Mar 3, 2010
Loading...

Share This Page