[Python-3000] Function annotations considered obfuscatory (Re: Conventions for annotation consumers)

[Josiah Carlson]

"Guido van Rossum" <guido at python.org> wrote:
> On 8/16/06, Josiah Carlson <jcarlson at uci.edu> wrote:
> > @docstring
> > @typechecker
> > @constrain_values
> > @__signature__([doc("frobination count"),
> >                 type(Number),
> >                 constrain_values(range(3,9))],
> >                [type(Number),
> >                 # This can be only 4, 8 or 12
> >                 constrain_values((4,8,12))], returns=type(Number))
> > def foo(a, b):
> 
> I think you just have disproved your point. Apart from losing a few
> string quotes this is just as unreadable as the example you started
> with, and those string quotes were due to a different convention for
> multiple annotations, not due to moving the information into a
> descriptor.
> 
> > Ultimately the full function definition (including decorators) is just
> > as cluttered, but now we can see that we have a function that takes two
> > arguments, without having to scan for 'name:' .  If it is necessary for
> > somone to know what kinds of values, types, docs, etc., then they can
> > use the documentation-producing tool that will hopefully come with their
> > annotation consumer(s).
> 
> The whole point of putting decorators up front was so that they share
> prime real estate ("above the fold" if you will :-) with the function
> signature. Claiming that what's in the decorators doesn't distract
> from the def itself doesn't make it true.

From using Python, my brain has become trained to look for new indent
levels, so when I'm looking for function definitions, this is what I see...

@CRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAP
@CRAPCRAPCRAPCRAPCRAPCRAPCRAP
@CRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAPCRAP
def foo(...):
    #stuff
    a = ...
    b = ...
    for ...:
        ...
    ...

In my opinion, decorators that don't include their own indentation for
readability do not distract from the def.  I would imagine that many
people (not just me) have trained themselves to look for new indent
levels, and would agree at some level with this.

Indents within decorators generally induce false positives during visual
scanning, but aside from including a line in the Python style guide
about not using multi-line decorators (and people being kind to readers
of their code), there's not much we can do.


> But, as I said 15 minutes ago, please stop worrying about this so
> much. Try to implement Collin's PEP (which doesn't have any
> constraints on the semantics or use of annotations). There's a Py3k
> sprint at Google (MV and NY) next week -- perhaps we can work on it
> there!

I'm trying to keep function *signatures* readable. Including one *small*
annotation per argument isn't a big deal, but when simple function
signatures (from the def to the suite colon) start spanning multiple
lines, they are getting both ungreppable and unreadable.  My primary
concern is users grepping, reading, and understanding.  If annotations
detract from any of those three, then the annotation is a waste of time
(in my opinion).

This was one of the concerns brought up in the decorator discussion, and
why none of the decorator proposals that sat between the def and the
closing paren even have typed-out examples listed as contenders on the
PythonDecorators wiki (they each get a bullet list as to why they suck).

But maybe I'm misremembering the discussion, maybe decorators make it
very difficult to visually scan for function definitions, and maybe
people want all that garbage in their function signature.


 - Josiah