Com relação à type-hints, eu também sou bastante fã.
Type hints, quando rodados junto com um type checker como o mypy, trazem muitas vantagens:
- Documentação.
Com certeza não substitui a documentação escrita, mas colocar type hints realmente facilita, pois além de não depender das docstrings, ainda temos a ferramenta checando para você, evitando que ela fica desetualizada.
Eu já vi muitas e muitas vezes (e escrevi também) documentação que até estava correta inicialmente, mas depois de um tempo ficou desatualizada. Por exemplo, dizer que um método retorna um dict
de str
-> int
, mas devido à algum refactoring ele às vezes retornava um valor str
(ao invés de int
), quebrando o cliente. Aqui o type checker vai detectar o problema imediatamente.