PEP-0318

[Andrew Durdin]

On Mon, 9 Aug 2004 11:34:39 +1000, Anthony Baxter
<anthonybaxter at gmail.com> wrote:
> 
> Guido has ruled out decorators at the top of function body, on the grounds
> that it looks like something that would be executed as part of the function,
> but isn't. FWIW, in the same thread he's noted that having docstrings where
> they are is problematic in this respect.

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?

The function signature should be first, and everything else to do with
it following. What might be a better general solution would be to have
a separate function header (containing docstrings, decorators, initial
attributes, etc) and body. Those parts in the header would be
parsed/executed only on function creation; the body being the part
that is executed when the function is called.

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

Note that I'm neither proposing such a thing for implementation in
Python, nor suggesting that the above syntax would be particularly
suitable :)   -- I'm just trying to illustrate the idea that
docstrings are better off after the signature.