PEP-0318

[Peter Hansen]

Arthur wrote:

> On the other hand, when I # comment a function, my instinct has always
> been to place the comment directly above the function, rather than in
> the body. Which I seem to think is common practice.  So I need to
> admit that with the freedom to comment anywhere, the fact that
> instinct, and nothing but, has led me to place it outside  and above
> the body  perhaps sabotages, a bit, my own and others position that
> decorators outside and above the function is somehow unnatural.

Comments are not decorators, and vice versa.

Editing tools have been evolved to subtly de-emphasize comments,
often, so that even when they appear above a function def they
do not inhibit (much) the process of finding the function def
when one scans the code.

Comments above the code are generally ignored, while decorators
may well be highly significant in the new world order.

Some people eschew comments above the functions and use only
doc-comments in Python, partly to avoid the situation where
the comments would obscure the function def.

It's probably not instinct, but experience (reading others' code)
that has led you to put the comments above function.

All in all, I'm not sure any of the points you raise sabotage
the position that decorators above the function are somehow
unnatural.

Unfortunately, decorators in the function are also unnatural.

In fact, they really need a separate dimension, but unfortunately
we're using a 2D system to describe them and probably have to
make a choice.  After, within, or before.

After is right out now, it seems.

Within has been discussed, and while many of us still find it
has the greatest merit (in the form of list-after-def), those
who argue it _can be_ harder to find speak the truth.  (Many
of us say "so what" to that, and still think the elegance and
other advantages of the approach outweigh that argument, but
we're not going to succeed with our argument. :-)

Therefore it will be before... the only important choice left
seems to be what bizarre and arbitrary punctuation symbol will
be chosen for the purpose.  (To be fair, it's not "arbitrary"
any more: clearly the sole requirement for this is how loud
and in-your-face the decorator symbol will be.  I don't know
when this sort of thing became considered good style for Python,
but this too is the new world order.)

-Peter