Réponse.

Contexte

En Python, la documentation du code via des docstrings est encouragée depuis les premières versions. Avec l'arrivée de Python 3.5 (PEP 484), des annotations de type (type hints) ont été ajoutées pour améliorer la lisibilité et le support des analyseurs de types (comme mypy, pyright, etc.). Ainsi, on peut combiner la documentation et la typage directement dans la définition des fonctions et des classes.

Problème

Sans annotations de type, il est difficile de comprendre rapidement sur quoi fonctionne une fonction et ce qu'on peut en attendre. Un manque de bonnes docstrings entraîne des malentendus sur l'interface et des erreurs d'utilisation. Si les type hints ou les docstrings sont mal utilisés, cela entrave l'analyse statique et complique la maintenance du code.

Solution

Utiliser des docstrings multilignes pour documenter l'objectif d'une fonction, ses paramètres et son retour, ainsi que des type hints pour indiquer explicitement les types des arguments et la valeur de retour.

Exemple de code :

def add_numbers(a: int, b: int) -> int:
    """
    Additionne deux nombres entiers et retourne le résultat.

    :param a: Premier addend, int
    :param b: Deuxième addend, int
    :return: Somme, int
    """
    return a + b

Caractéristiques clés :

La docstring est stockée dans doc et accessible pour IDE, help(), générateurs automatiques de documentation.
Les annotations de type sont accessibles via annotations; elles n'influent pas sur l'exécution du code, seulement pour l'analyse.
L'application combinée facilite la maintenance à grande échelle et l'intégration des nouveaux programmeurs.

Questions pièges.

Les annotations de type peuvent-elles affecter l'exécution du programme ?

Non. Les annotations de type (type hints) ne sont pas vérifiées par l'interpréteur Python lors de l'exécution et servent uniquement aux analyseurs et IDE, ainsi qu'à la génération automatique de documentation. Elles ne provoquent pas d'erreurs d'exécution et sont toujours optionnelles.

Peut-on utiliser des annotations de type pour restreindre les valeurs des paramètres ?

Non. Spécifier un type, par exemple x: int, n'interdit pas le passage de valeurs d'un autre type dans la pratique. Pour cela, on peut utiliser des vérifications à l'exécution (assert/isinstance), mais pas des type hints — ils ne sont pas vérifiés automatiquement.

Peut-on utiliser des commentaires # type: ... au lieu des annotations ? Pourquoi cela pourrait-il être nécessaire ?

Oui, cela est permis si une compatibilité avec Python 2 ou d'anciens codes est nécessaire. Par exemple :

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

Cela est compris par mypy et des outils similaires au même titre que la syntaxe moderne, mais dans de nouveaux projets, il est préférable d'utiliser les annotations standard.

Erreurs typiques et anti-patterns

Absence de docstring ou docstring vide pour les fonctions et classes publiques.
Indication incorrecte des types — par exemple, List au lieu de list ou erreurs typographiques dans les types (surtout avec des collections complexes).
Utilisation de type hints sans mise à jour de la documentation et vice versa.

Exemples de la vie réelle

Cas négatif

Dans un grand projet, les fonctions ne sont pas du tout dotées de docstrings et de type hints — le développeur passe beaucoup de temps à comprendre et à déboguer, commettant souvent des erreurs avec les types et l'objectif des données d'entrée.

Avantages :

Écriture rapide du code au moment du démarrage.

Inconvénients :

Grande difficulté de maintenance, l'intégration de nouveaux employés est grandement retardée.
Difficile de détecter les erreurs si les types des paramètres sont mélangés.

Cas positif

Toutes les fonctions publiques ont des docstrings détaillées et des type hints corrects, ce qui permet aux IDE et aux analyseurs de détecter rapidement les erreurs de type et de générer automatiquement la documentation pour l'API.