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

Guido van Rossum guido at python.org
Wed Aug 16 20:17:33 CEST 2006

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 > > @constrainvalues > > @signature([doc("frobination count"), > > type(Number), > > constrainvalues(range(3,9))], > > [type(Number), > > # This can be only 4, 8 or 12 > > constrainvalues((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/)

More information about the Python-3000 mailing list