Docstrings considered too complicated

[Steven D'Aprano]

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