Docstrings considered too complicated

  • Thread starter Andreas Waldenburger
  • Start date
A

Andreas Waldenburger

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
 
J

Jonathan Gardner

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

John Posner

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
 
S

Steven D'Aprano

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

Roy Smith

Steven D'Aprano said:
# 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.
 
J

Jack Diederich

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
 
J

John Roth

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

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
 
A

Andreas Waldenburger

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
 
J

Jean-Michel Pichavant

Andreas said:
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
 
T

Tim Daneliuk

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
 
A

Andreas Waldenburger

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
 
A

Andreas Waldenburger


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
 
R

Roy Smith

Tim Daneliuk said:
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.
*/
 
P

Phlip

Andreas said:
"""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?
 
R

Richard Brodie

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

Jean-Michel Pichavant

Andreas said:
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
 
J

Jean-Michel Pichavant

Roy said:
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
 
M

mk

Roy said:
/**
* 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
 
M

Mel

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

Grant Edwards

Andreas said:
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.
 

Ask a Question

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

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,480
Members
44,900
Latest member
Nell636132

Latest Threads

Top