[Python-ideas] Conventions for Python code documentation (was: PEP 484 (Type Hints) -- first draft round)

[Chris Barker]

On Mon, Jan 19, 2015 at 8:42 PM, Guido van Rossum <guido at python.org> wrote:

> On Mon, Jan 19, 2015 at 5:04 PM, Chris Barker - NOAA Federal <
> chris.barker at noaa.gov> wrote:
>
>> I always teach that the @ syntax is a decoration, not a decorator,
>> whereas a decorator is a function that takes a function and returns another
>> function ( usually a customized version of the passed in function). This
>> distinction between decorators and decoration syntax keeps the door open to
>> do just about anything with decorations, but am I the only one that thinks
>> it's a bad idea to have it be for "any old thing we want to hang off a
>> function"?
>>
>
> I think you're the only one who makes this distinction.
>

No, I'm not -- take a look at any number of tutorial sites, and answers for
newbies on SO, etc. I used to teach decorators without making the
distinction, and got a lot of confused students. maybe the distinction is
only useful for pedagogical purposes, but I introduced it here 'cause it's
a bit harder to talk about when a "decorator" can be either a function the
behaves a certain way or the @something line in the code.


> In common use "decorator" is used to describe both the syntax and the
> function invoked by the syntax. "Decoration" is never (well, very rarely)
> used. And calling any function that takes a function and returns one a
> decorator feels overreaching -- I'd only call it a decorator if it is
> intended to use with the decorator syntax.
>

sure -- I'm having a hard time coming up with the word s to describe what
I"m talking about as  "proper" decorator. The truth is, you can put any
callable that takes at least one argument after that @. And I'm not
suggesting that python should enforce anything in particular about that.
What I am suggesting is that we should not officially suggest that you
should use a decorator for any old thing that doesn't fit the usual sprit
of decorators.

A decorator that simply adds stuff to the docstring feels pretty ugly to
me, particular if it goes beyond docs to specifying something important
about the typing, etc.

Hard to draw a line there, but I  think we should keep the spirit of
decorators in mind.

But enough said.

-Chris



-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chris.Barker at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20150120/dc44f7b9/attachment.html>