[Python-Dev] Allow annotations using basic types in the stdlib?

[R. David Murray]

I agree with Steve.  There is *cognitive* overhead to type annotations.
I find that they make Python code harder to read and understand.  So I
object to them in the documentation and docstrings as well.  (Note:
while I agree that the notation is compact for the simple types, the
fact that it would appear for some signatures and not for others is a
show stopper from my point of view...consistency is important to reducing
the cognitive overhead of reading the docs.)

I'm dealing with the spread of annotations on my current project,
having to ask programmers on the team to delete annotations that they've
"helpfully" added that to my mind serve no purpose on a project of the
size we're developing, where we aren't using static analysis for anything.

Maybe I'm being a curmudgeon standing in the way of progress, but I'm
pretty sure there are a number of people in my camp :)

On Mon, 06 Nov 2017 16:22:23 +0000, Steve Holden <steve at holdenweb.com> wrote:
> While I appreciate the value of annotations I think that *any* addition of
> them to the stdlib would complicate an important learning resource
> unnecessarily. S
> 
> Steve Holden
> 
> On Mon, Nov 6, 2017 at 4:07 PM, Victor Stinner <victor.stinner at gmail.com>
> wrote:
> 
> > Related to annotations, are you ok to annotate basic types in the
> > *documentation* and/or *docstrings* of the standard library?
> >
> > For example, I chose to document the return type of time.time() (int)
> > and time.time_ns() (float). It's short and I like how it's formatted.
> > See the current rendered documentation:
> >
> > https://docs.python.org/dev/library/time.html#time.time
> >
> > "Annotations" in the documentation and docstrings have no impact on
> > Python runtime performance. Annotations in docstrings makes them a few
> > characters longer and so impact the memory footprint, but I consider
> > that the overhead is negligible, especially when using python3 -OO.