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

[Guido van Rossum]

On 8/16/06, Josiah Carlson <jcarlson at uci.edu> wrote:
>
> "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 ...:
>         ...
>     ...

Well, then the problem becomes finding the tiny 'def' between all that CRAP.

> 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.

But notice that the example *did* include multi-line decorators with
indented continuation lines.

> 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.

There's another style:

type_a = {"foo": some_type_for_framework_foo, "bar": some_other_type, etc.}
type_b = {...similar...}

def my_fun(a: type_a, b: type_b) -> type_c:
    ...

This works just as well for the list style of having multiple annotations.

If you write a lot of code that uses multiple annotations, I'd be very
surprised if there weren't a bunch of common combinations that could
be shared like this.

> > 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).

What exactly are you grepping for where a multi-line arglist would get
in the way? The most complicated pattern for which I grep is probably
something along the lines of '^def \w+\('.

> 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.

They don't want it, but if they're forced to have it occasionally
they'll cope. I still think you're way overestimating the importance
of this use case.

-- 
--Guido van Rossum (home page: http://www.python.org/~guido/)