Docstrings considered too complicated

[Roy Smith]

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