Respuesta.

Historia de la cuestión

En Python se fomenta la documentación del código a través de docstring desde las primeras versiones. Con la llegada de Python 3.5 (PEP 484) se añadieron anotaciones de tipos (type hints) para mejorar la legibilidad y la compatibilidad con analizadores de tipos (por ejemplo, mypy, pyright, etc.). De esta manera, se pueden combinar la documentación y la tipificación directamente en la definición de funciones y clases.

Problema

Sin anotaciones de tipos es difícil entender rápidamente con qué trabaja una función y qué se puede esperar de ella. La falta de buenos docstring lleva a malentendidos sobre la interfaz y errores de uso. Si se utilizan incorrectamente los type hints o docstrings, esto interfiere con el análisis estático y empeora el soporte del código.

Solución

Utilizar docstring de varias líneas para documentar el propósito de la función, parámetros y resultados, así como type hints para indicar explícitamente los tipos de los argumentos y el valor de retorno.

Ejemplo de código:

def add_numbers(a: int, b: int) -> int:
    """
    Suma dos números enteros y devuelve el resultado.

    :param a: Primer sumando, int
    :param b: Segundo sumando, int
    :return: Suma, int
    """
    return a + b

Características clave:

El docstring se almacena en doc y está disponible para IDE, help(), generadores de documentación automática.
Las anotaciones de tipos están disponibles a través de annotations; no afectan la ejecución del código, son solo para análisis.
La combinación de ambos facilita el soporte a gran escala y la integración de nuevos programadores.

Preguntas engañosas.

¿Pueden las anotaciones de tipos afectar la ejecución del programa?

No. Las anotaciones de tipos (type hints) no son verificadas por el intérprete de Python durante la ejecución y sirven exclusivamente para analizadores e IDE, así como para la generación automática de documentación. No provocan errores en tiempo de ejecución y son siempre opcionales.

¿Se pueden usar las anotaciones de tipos para restringir los valores de un parámetro?

No. Especificar un tipo, por ejemplo, x: int no impide la transmisión de un valor de otro tipo en la práctica. Para eso se pueden utilizar verificaciones en tiempo de ejecución (assert/isinstance), pero no type hints — no se verifican automáticamente.

¿Se pueden utilizar comentarios # type: ... en lugar de anotaciones? ¿Para qué puede ser necesario esto?

Sí, es permitido si se necesita compatibilidad con Python 2 o con bases de código antiguas. Por ejemplo:

def foo(x, y):     # type: (int, str) -> bool
    pass

Esto es entendido por mypy y herramientas similares al mismo nivel que la sintaxis moderna, pero en nuevos proyectos es mejor utilizar las anotaciones estándar.

Errores comunes y anti-patrones

Ausencia de docstring o docstring vacío en funciones y clases públicas.
Especificación incorrecta de tipos — por ejemplo, List en lugar de list o errores tipográficos en tipos (especialmente con colecciones complejas).
Uso de type hints sin actualizar la documentación y viceversa.

Ejemplo de la vida real

Caso negativo

En un gran proyecto, las funciones carecen por completo de docstring y type hints — el desarrollador pasa mucho tiempo estudiando y depurando, a menudo se confunde con los tipos y la finalidad de los datos de entrada.

Pros:

Rápida escritura de código al inicio.

Contras:

Grandes dificultades de mantenimiento, la integración de nuevos empleados se retrasa considerablemente.
Es difícil detectar errores si se confunden los tipos de los parámetros.

Caso positivo

Todas las funciones públicas tienen un docstring detallado y type hints correctos, lo que permite a los IDE y analizadores detectar rápidamente errores de tipos y generar automáticamente la documentación para la API.