[Python-Dev] Type hints -- a mediocre programmer's reaction

[Cory Benfield]

On 21 April 2015 at 12:23, Gustavo Carneiro <gjcarneiro at gmail.com> wrote:
> Documentation is not checked.  It often loses sync with the actual code.
> Docs say one thing, code does another.

Agreed. I don't think anyone would disagree here. I'm talking from the
position of being a library author, where supporting versions of
Python lower than 3.5 will be a reality for at least 5 more years. I
will not be able to inline my type hints, so they'll have to go in
stub files, and now we've got the same problem: type hints can go out
of step just as easily as documentation can.

> Documenting types in docstrings forces you to repeat yourself.  You have to
> write the parameter names twice, once in the function definition line,
> another in the docstring.  And you need to understand the syntax of whatever
> docstring format will be used to check the code.

Yes, but I'm repeating myself O(small integer) lines away from where I
first wrote it. The maintenance burden of keeping those things in step
is not very high. As for your last point, my code is not checked
against my docstrings, primarily for the reasons I mentioned in my
original email. My docstrings are merely rendered into documentation.

> I'm sure I'm not the only one that thinks that type hints actually *improve
> readability*.

In some cases, sure. No contest.

> but I am certain that most of the time the type hints make the
> code easier to read because you don't have to spend so much mental effort
> trying to figure out "gee, I wonder if this parameter is supposed to be
> bool, string, or int?"

Yes. If you spend a lot of your time doing this, then type hints will
help you, *assuming* the programmer who originally wrote the ambiguous
code diligently maintains the type hints. I have no reason to believe
that a programmer whose code is that ambiguous is going to do that, or
even write type hints at all.

The bigger problem is that, previously, Python functions never took
bool, string, or int. They took 'object that can be evaluated in a
boolean context', 'object that behaves like strings in some undefined
way', and 'objects that behave like ints in some undefined way'. The
type hint you provide is *not helpful*. What I *need* is a type hint
that says 'object that has the .endswith() method' or 'object that can
be safely cast to a string', so I can tell whether I can pass you a
custom URL class that happens to render into a textual URL or whether
it definitely has to be a string object. But you can't express that
relationship in this model, so you will just say 'string', and now I
will turn off type checking because the type hinter keeps shouting at
me for using my URLBuilder object.

If you only work with primitive types and only want your users to use
primitive types, this proposal almost certainly works brilliantly. If
you *don't*, this proposal begins to become extremely uncomfortable
extremely fast.

> Even if it only helps in the simplest cases, it saves the reader of the code
> a lot of effort if you add up all those little cases together.
>
> My suggestion, wherever an annotated type is too complex, don't annotate it.
> If you do /only/ the simple cases, the end result is easier to read.

If that's genuinely the bar for success for this PEP, then fine, I
wish it the best. I'd *like* a PEP that can deal with the complex
cases too, but I freely admit to having no idea how such a thing may
be implemented. All I can say is that I think this PEP will have
limited uptake amongst many third-party libraries, particularly the
complex ones.