[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.python

Docstrings considered too complicated

Andreas Waldenburger

2/24/2010 8:23:00 PM

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!
102 Answers

Jonathan Gardner

2/24/2010 9:55:00 PM

0

On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger
<usenot@geekmail.invalid> 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
jgardner@jonathangardner.net

John Posner

2/25/2010 12:18:00 AM

0

On 2/24/2010 4:54 PM, Jonathan Gardner wrote:
> On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger
> <usenot@geekmail.invalid> 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

Steven D'Aprano

2/25/2010 12:23:00 AM

0

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

Roy Smith

2/25/2010 2:28:00 AM

0

In article <pan.2010.02.25.00.22.45@REMOVE.THIS.cybersource.com.au>,
Steven D'Aprano <steven@REMOVE.THIS.cybersource.com.au> 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.

Jack Diederich

2/25/2010 5:11:00 AM

0

On Wed, Feb 24, 2010 at 4:54 PM, Jonathan Gardner
<jgardner@jonathangardner.net> wrote:
> On Wed, Feb 24, 2010 at 12:23 PM, Andreas Waldenburger
> <usenot@geekmail.invalid> 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

John Roth

2/25/2010 8:51:00 PM

0

On Feb 24, 1:23 pm, Andreas Waldenburger <use...@geekmail.INVALID>
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

Andreas Waldenburger

2/26/2010 12:42:00 PM

0

On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth
<johnroth1@gmail.com> wrote:

> On Feb 24, 1:23 pm, Andreas Waldenburger <use...@geekmail.INVALID>
> 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!

Jean-Michel Pichavant

2/26/2010 2:50:00 PM

0

Andreas Waldenburger wrote:
> On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth
> <johnroth1@gmail.com> wrote:
>
>
>> On Feb 24, 1:23 pm, Andreas Waldenburger <use...@geekmail.INVALID>
>> 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

Tim Daneliuk

2/26/2010 3:10:00 PM

0

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 tundra@tundraware.com
PGP Key: http://www.tundrawar...

Andreas Waldenburger

2/26/2010 4:35:00 PM

0

On Fri, 26 Feb 2010 15:50:25 +0100 Jean-Michel Pichavant
<jeanmichel@sequans.com> 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!