Docstrings considered too complicated
roy at panix.com
Thu Feb 25 03:27:55 CET 2010
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.
More information about the Python-list