Docstrings considered too complicated

[Andreas Waldenburger]

On Thu, 25 Feb 2010 12:51:00 -0800 (PST) John Roth
<johnroth1 at gmail.com> wrote:

> On Feb 24, 1:23 pm, Andreas Waldenburger <use... at geekmail.INVALID>
> wrote:
> > 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


-- 
INVALID? DE!