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

Josiah Carlson jcarlson at uci.edu
Wed Aug 16 20:12:20 CEST 2006

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

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.

More information about the Python-3000 mailing list