Back in 2015 with the release of Python 3.5 a new feature, type hints were revealed. As proposed in PEP484. This provides developers with a means of annotating expected types in their Python code.

Type hints can be added to function arguments, function return types, and variables. One thing to note is that type hints are not enforced by the Python compiler, they are as the name implies, simply hints.

When using a dynamically typed language such as Python, one may ask why bother with the extra effort involved with adding type hints and adding seemingly superfluous code.

Improved Clarity

One of the main benefits of utilising type hints in Python is that they drastically improve the clarity of the code by definitively documenting the required types.

This can be useful for anyone from a solo developer, right through to large engineering teams of many hundreds of developers. As the size of a team working on a codebase grows, so does then benefit gained by utilising type hints.

Consider the following example, comparing the same function with and without type hints. It is very easy to see which one is easier to comprehend what types are expected without the need to read through the function definition to attempt figuring out what types should be passed in.

Documenting the types could be achieved with standard Python docstrings, however defining the types in docstrings still requires a developer to read through a potentially large block of text to extract singular pieces of information regarding what types are accepted and returned by the function.

Tooling

The other big benefit that type hints provide for developers is the increasing amount of tooling that can make use of type hints. Compatible tooling includes linters, static type checkers.

Having tools that can hook into type annotations and warn developers of situations where incorrect types are being assigned to variables, passed to or returned from a function does wonders for reducing the risk of a TypeError being raised at runtime.

So Why Bother?

For very short, or one-off scripts to do some task then it is likely not worth the added effort involved with adding type hints. For anything else beyond a trivial script, it is more than worth the effort.

For solo developers, coming back to code weeks, months, or even years later, type hints can go a long way in comprehending the code.

In the case of small teams through to large distributed teams, the benefit is even greater due to the constant need to work with others code, and when onboarding new team members that are completely new to the codebase.