PEP-0318

[Mark Bottjer]

Andrew Durdin wrote:
> I honestly believe that having docstrings where they are is better
> than having them before the function signature; how many
> function-commenting standards have you seen where the function name is
> repeated in the first line of the comment so that you know what
> function is being talked about when you start reading the comment?

I'm torn on this one, frankly. I agree that having it before the 
function is very much putting the cart before the horse, and leads to 
redundancy to keep it all straight, but I also agree that having it 
inside the function muddies up the function implementation, and is not 
the first place one might think to look for such information.

> This in conception is something like the following:
> 
> def foo(bar, baz=None):
>     header:
>         """Frobulates bar, and calls baz if it is not None."""
>         .decorate(decorator_func)
>         .attribute = "qux"
>     body:
>         pass

I think that this has been proposed before, but was rejected for reasons 
I can't remember. But, as a guess, GvR's argument that one should not 
have to "look inside" a function to see what it is would apply.

And FWIW, the body statement is probably unnecessary. All that really 
needs to be delineated is the header; everything that isn't header is by 
definition the body. Just my $0.02.

   -- Mark