Docstring in Python: Best Practice, Esempi e Strumenti di Validazione
La docstring (documentation string) è un'importante funzionalità di
Python che permette di documentare moduli, classi, metodi e funzioni
direttamente nel codice. È una stringa che si posiziona subito dopo la
definizione di una funzione, classe o modulo e serve a descrivere il
comportamento o l'uso di quell'elemento. Le docstring vengono utilizzate da
strumenti di documentazione automatica come Sphinx e da
strumenti interattivi come help().
Il seguente frammento di codice mostra un esempio di Docstring:
def somma(a: int | float, b: int | float) -> int | float:
"""
Calcola la somma di due numeri.
Parametri:
a (int, float): Primo numero.
b (int, float): Secondo numero.
Restituisce:
int, float: La somma di a e b.
"""
return a + b
La docstring è la porzione di testo inserita all'interno delle """"""
inserite all'inizio della definizione di funzione.
Componenti Principali di una Docstring
Le docstring sono strutturate in modo da essere facilmente leggibili e utilizzabili dagli strumenti di documentazione.
Innanzitutto, è importante includere una breve descrizione che spiega in poche parole cosa fa la funzione. Questo aiuta subito a capire lo scopo principale dell'elemento documentato.
Poi, devono essere elencati e descritti i parametri in ingresso, specificando per ciascuno il tipo e il loro scopo. Questo chiarisce quali valori la funzione si aspetta come input e come devono essere utilizzati.
Successivamente, è fondamentale descrivere il valore di restituzione della funzione, specificando il tipo di valore che la funzione restituirà. Questa parte aiuta a comprendere cosa ci si può aspettare come risultato dell'esecuzione della funzione.
In alcune situazioni, è utile includere informazioni sulle eccezioni che la funzione potrebbe sollevare, se ve ne sono. Questo consente agli sviluppatori di sapere quali errori possono verificarsi e come gestirli.
Infine, puoi aggiungere note aggiuntive per fornire dettagli supplementari sull'uso della funzione, eventuali algoritmi utilizzati o riferimenti pertinenti. Questo può includere spiegazioni più approfondite o informazioni contestuali che non rientrano nelle altre sezioni.
Esempio Completo con tutti i componenti
def divisione(a: int | float, b: int | float) -> float:
"""
Divide il numero a per il numero b.
Parametri:
a (int, float): Il dividendo.
b (int, float): Il divisore, deve essere diverso da zero.
Restituisce:
float: Il risultato della divisione di a per b.
Solleva:
ZeroDivisionError: Se b è uguale a zero.
"""
if b == 0:
raise ZeroDivisionError("Divisione per zero non consentita.")
return a / b
Linee Guida Per Una Corretta Compilazione della Docstring
Una docstring ben scritta deve rispettare alcune convenzioni e best practices per garantire chiarezza e coerenza. In primo luogo, è fondamentale posizionare la docstring immediatamente dopo la definizione di una funzione, metodo, classe o modulo, senza inserire altre righe di codice nel mezzo.
La descrizione fornita dalla docstring deve essere concisa e chiara: la prima riga dovrebbe sempre offrire una spiegazione breve e diretta di ciò che l'elemento fa. Se sono necessari ulteriori dettagli, come informazioni sui parametri o eccezioni, questi possono essere aggiunti nelle righe successive.
Per garantire uniformità nella documentazione, è consigliabile adottare uno dei formati riconosciuti per la scrittura delle docstring, come il formato Google, il formato Sphinx (basato su reStructuredText) o il formato NumPy. Seguire uno di questi stili aiuta a mantenere la documentazione leggibile e facilmente utilizzabile con strumenti automatici.
Infine, il tono della docstring dovrebbe essere chiaro e neutro. Si raccomanda di utilizzare frasi all'indicativo e al tempo presente, evitando un linguaggio soggettivo. Lo scopo è descrivere il comportamento del codice in modo oggettivo, senza opinioni personali.
PEP Associate alla Docstring
La documentazione delle docstring in Python è principalmente regolata dalla PEP 257, che stabilisce lo stile e le convenzioni da seguire per garantire che le docstring siano pulite, leggibili e coerenti. Secondo queste linee guida, ogni modulo, funzione, classe o metodo pubblico dovrebbe essere corredato da una docstring che ne spieghi il funzionamento.
La prima riga di una docstring deve sempre essere una descrizione concisa e diretta dell'elemento. Per quanto riguarda la formattazione, è importante utilizzare le triple virgolette per delimitare le docstring, anche quando contengono una sola riga. Se si tratta di una docstring breve, questa dovrebbe essere scritta e chiusa sulla stessa riga. Al contrario, le docstring più lunghe, che occupano più righe, dovrebbero avere una riga vuota prima e dopo il contenuto descrittivo.
Un'altra PEP rilevante è la PEP 8, che non solo regola lo stile generale del codice Python, ma offre anche linee guida specifiche per garantire una buona scrittura delle docstring.
Strumenti di Validazione della Docstring
Esistono vari strumenti che possono aiutare a verificare se le docstring sono scritte correttamente e seguono le linee guida stabilite dalla PEP 257 e PEP 8. Alcuni compilatori e IDE offrono supporto per il controllo delle docstring direttamente nell'ambiente di sviluppo, ma esistono anche strumenti esterni molto utili per questo scopo.
Un esempio è pydocstyle, un tool che analizza il codice Python per verificare che le docstring rispettino le regole della PEP 257, segnalando eventuali violazioni di stile.
Un'altra opzione è flake8-docstrings, un plugin per il noto linter Flake8, che aggiunge la capacità di estendere il controllo delle docstring, assicurandosi che rispettino le convenzioni stabilite.
Infine, anche Sphinx, pur essendo principalmente uno strumento per generare documentazione, può essere utilizzato per rilevare errori e incongruenze nelle docstring, contribuendo a produrre una documentazione più coerente e accurata.
Questi strumenti facilitano il mantenimento di standard elevati nella scrittura delle docstring.
Esempio di Verifica con pydocstyle
Supponiamo di avere il frammento di codice python presentato
precedentemente nell'articolo che implementava la funzione somma all'interno di un file somma.py. Eseguendo pydocstyle otterremo il seguente avviso:
$ pydocstyle example.py
example.py:1 in public function `moltiplica`:
D103: Missing docstring in public module
L'errore ci indica che non è presente una docstring per il modulo.
Conclusione
Le docstring sono uno strumento essenziale per mantenere il codice Python ben documentato e facilmente comprensibile. Seguendo le linee guida della PEP 257 e utilizzando strumenti di validazione, puoi garantire che il tuo codice sia accessibile, ben strutturato e professionale.
