[Python-Dev] Type hints -- a mediocre programmer's reaction (original) (raw)

Cory Benfield cory at lukasa.co.uk
Tue Apr 21 14:47:11 CEST 2015

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.

More information about the Python-Dev mailing list