[Python-Dev] Re: Decorators after 'def' should be reconsidered

[barnesc at engr.orst.edu]

>> -----------------------------------------------
>> Option A
>> -----------------------------------------------
>> 
>> """
>> Hi,
>> 
>> Performs a binary operation.
>> 
>> Docstring.
>> """
>> @staticmethod
>> @synchronized(lockvar)
>> def f(a, b):
>>     return a + b
>> 
>> """
>> Now,
>> 
>> Performs a simple operation.
>> """
>> @classmethod
>> def g(a):
>>     return a
>> 
>> -----------------------------------------------
>> Option B
>> -----------------------------------------------
>> 
>> def f(a, b):
>>     @staticmethod
>>     @synchronized(lockvar)
>>     """
>>     Hi,
>> 
>>     Performs a binary operation.
>> 
>>     Docstring.
>>     """
>>     return a + b
>> 
>> def g(a):
>>     @classmethod
>>     """
>>     Now,
>> 
>>     Performs a simple operation.
>>     """
>>     return a
>> 
>> 
>> Now, forget everything you've learned about Python.
>> Forget that @ symbols are ugly.
>> 
>>  - For which method is it visually easier to find the function def?
>
>None of them. A good syntax coloring would even make it easier in fact. On
>the second hand, the Option B makes it much harder to find the function
>code once you've found the function def.

Option B makes it easier to find the function def, because the def is the
only line that is not indented.  I can scan straight down the page and
instantly find the two function 'def's.   For Option A, I have to scan
line by line.

>>  - For which method is the code in the most logical order?
>
>Option A of course. Since the decorator can be seen as a function that takes
>the defined function as it's first parameter, it's logical to place the
>decorator before the definition.


I consider the function def to be the most important line of the
entire function.

Thus it follows that it should be the first line.

Thinking further, it makes sense to define a function, then define
various properties of the function in indented blocks, since the
properties are 'contained' in the function.

I do agree with your assessment for decorators.  However, you
have to weigh the 'priority' of the decorator against the priority
of the def line.  In my mind, the def line wins, and so should be
first.

Again, of course, there's the advantage of being able to skim down
the left column (which is mostly whitespace) and locate function
entrance points quickly.  For me, this increases the perceived
organization of the code, much like labelled boxes help organize
the papers in my room (locate the box quickly, then sort through
it).

See:

http://oregonstate.edu/~barnesc/temp/option/optiona.html
http://oregonstate.edu/~barnesc/temp/option/optionb.html

Consider the difficulty of scanning such code, when there is
a long module, with nested functions inside a class.

>I don't understand how grep can be "confused" by the decorators before the
>def. Are we talking about the same program ???

I refer to searching done by the eye.

 - Connelly