Docstrings considered too complicated

Steven D'Aprano steven at
Thu Feb 25 01:22:45 CET 2010

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.


More information about the Python-list mailing list