Risposta.

Storia della questione

In Python, si incoraggia la documentazione del codice tramite docstring fin dalle prime versioni. Con l'arrivo di Python 3.5 (PEP 484) sono state aggiunte le annotazioni dei tipi (type hints) per migliorare la leggibilità e il supporto per gli analizzatori di tipi (come mypy, pyright, ecc.). In questo modo, è possibile combinare documentazione e tipizzazione direttamente nelle definizioni di funzioni e classi.

Problema

Senza annotazioni di tipo, è difficile comprendere rapidamente con cosa lavora una funzione e cosa ci si aspetta da essa. La mancanza di buoni docstring porta a malintesi sull'interfaccia e a errori di utilizzo. Se si utilizzano in modo errato i type hints o i docstring, ciò ostacola l'analisi statica e peggiora il supporto del codice.

Soluzione

Utilizzare docstring multi-linea per documentare lo scopo della funzione, i parametri e il risultato, oltre ai type hints per specificare esplicitamente i tipi degli argomenti e del valore restituito.

Esempio di codice:

def add_numbers(a: int, b: int) -> int:
    """
    Somma due numeri interi e restituisce il risultato.

    :param a: Primo addendo, int
    :param b: Secondo addendo, int
    :return: Somma, int
    """
    return a + b

Caratteristiche principali:

Il docstring è memorizzato in doc ed è accessibile per IDE, help(), generatori automatici di documentazione
Le annotazioni dei tipi sono disponibili tramite annotations; non influenzano l'esecuzione del codice, solo per l'analisi
L'uso combinato facilita il supporto su larga scala e l'onboarding di nuovi programmatori

Domande ingannevoli.

Le annotazioni dei tipi possono influenzare l'esecuzione del programma?

No. Le annotazioni dei tipi (type hints) non vengono verificate dall'interprete Python durante l'esecuzione e servono esclusivamente per gli analizzatori e le IDE, così come per la generazione automatica della documentazione. Non causano errori di runtime e sono sempre opzionali.

È possibile utilizzare le annotazioni dei tipi per limitare i valori dei parametri?

No. Specificare il tipo, ad esempio, x: int non impedisce effettivamente il passaggio di un valore di un altro tipo. A tale scopo, è possibile utilizzare controlli di runtime (assert/isinstance), ma non i type hints — non vengono verificati automaticamente.

È possibile utilizzare commenti # type: ... invece delle annotazioni? A cosa serve?

Sì, è consentito se è necessaria la compatibilità con Python 2 o con vecchie codebase. Ad esempio:

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

Questo è compreso da mypy e strumenti simili insieme alla sintassi moderna, ma nei nuovi progetti è meglio utilizzare le annotazioni standard.

Errori tipici e anti-pattern

Mancanza di docstring o docstring vuoto per funzioni e classi pubbliche
Errata specificazione dei tipi — ad esempio, List invece di list o errori di battitura nei tipi (soprattutto con collezioni complesse)
Utilizzo di type hints senza aggiornare la documentazione e viceversa

Esempio dalla vita reale

Caso negativo

In un grande progetto, le funzioni non sono affatto fornite di docstring e type hints — lo sviluppatore spende molto tempo a studiare e fare debug, commettendo spesso errori con i tipi e lo scopo dei dati di input.

Pro:

Scrittura rapida del codice all'inizio

Contro:

Grandi difficoltà di mantenimento, onboarding dei nuovi dipendenti molto prolungato
Difficile intercettare errori se i tipi dei parametri sono scambiati

Caso positivo

Tutte le funzioni pubbliche hanno docstring dettagliati e corretti type hints, il che consente a IDE e analizzatori di rilevare rapidamente errori di tipo e generare automaticamente la documentazione per l'API.