Come documentare il codice Python usando Docstrings

Senza una documentazione adeguata, può essere difficile comprendere, mantenere ed eseguire il debug del codice. In Python, puoi usare le docstring per fornire descrizioni concise ed esempi di come funziona il codice.

Cosa sono le Docstring?

Le docstring sono stringhe che puoi aggiungere al tuo codice Python per spiegare cosa fa e come usarlo. Il pezzo di codice può essere a Funzione Python, un modulo o una classe.

Le docstring assomigliano molto ai commenti Python standard, ma presentano alcune differenze. I commenti Python forniscono informazioni aggiuntive agli sviluppatori sul funzionamento interno del codice, come dettagli di implementazione o avvertimenti da tenere a mente quando si estende il codice.

D'altra parte, le docstring forniscono principalmente informazioni agli utenti del codice che potrebbero non aver necessariamente bisogno di conoscerne i dettagli di implementazione, ma hanno bisogno di capire cosa fa e come usarlo.

Come scrivere Docstring

In genere includi docstring all'inizio del blocco di codice che desideri documentare. Devi racchiuderli tra virgolette triple (). Puoi scrivere docstring di una riga o docstring di più righe.

Le docstring di una riga sono adatte per codice semplice che non richiede molta documentazione.

Di seguito è riportato un esempio di una funzione chiamata moltiplica. La docstring spiega che la funzione moltiplica prende due numeri, li moltiplica e restituisce il risultato.

defmoltiplicare(a, b):
Moltiplica due numeri e restituisce il risultato
ritorno a * b

Usa docstring multilinea per codice più complesso che richiede una documentazione dettagliata.

Considera la seguente classe di auto:

classeAuto:

 UN classeche rappresentanoUNautooggetto.
 Attributi:
 chilometraggio (float): il chilometraggio attuale dell'auto.
 Metodi:
 drive (miglia): Guida l'auto per il numero di miglia specificato.

def__dentro__(auto, chilometraggio):
 self.chilometraggio = chilometraggio
defguidare(sé, miglia):

 Guida la macchina per il numero di miglia specificato.
 Argomenti:
 miglia (float): il numero di miglia da guidare.
 Ritorna:
Nessuno

 self.chilometraggio += miglia

La docstring per la classe precedente descrive ciò che la classe rappresenta, i suoi attributi ei suoi metodi. Nel frattempo, le docstring per il metodo drive forniscono informazioni su cosa fa il metodo, gli argomenti che si aspetta e cosa restituisce.

Questo rende più facile per chiunque lavori con questa classe capire come usarla. Gli altri vantaggi dell'utilizzo di docstring includono:

• Manutenibilità del codice: fornendo una chiara descrizione di come funziona il codice, le docstring aiutano gli sviluppatori a modificare e aggiornare il codice senza introdurre errori.
• Collaborazione più semplice: quando diversi sviluppatori collaborano alla stessa base di codice, ad esempio con il Strumento di condivisione live di Visual Studio—docstrings consente agli sviluppatori di documentare il codice in modo coerente in modo che tutti i membri del team possano capirlo.
• Migliore leggibilità del codice: le docstring forniscono un riepilogo di alto livello di cosa fa il codice e cosa lo consente chiunque legga il codice per comprenderne rapidamente lo scopo senza passare attraverso l'intero codice bloccare.

Formati Docstring

Una buona docstring dovrebbe descrivere cosa fa un pezzo di codice, gli argomenti che si aspetta e i dettagli di implementazione se necessario. Dovrebbe includere in particolare tutti i casi limite di cui chiunque utilizzi il codice dovrebbe essere a conoscenza.

Un formato docstring di base ha le seguenti sezioni:

• Riga di riepilogo: un riepilogo di una riga di ciò che fa il codice.
• Argomenti: informazioni sugli argomenti previsti dalla funzione, inclusi i relativi tipi di dati.
• Valore di ritorno: Informazioni sul valore di ritorno della funzione incluso il suo tipo di dati.
• Solleva (facoltativo): informazioni su eventuali eccezioni che la funzione può sollevare.

Questo è solo un formato di base in quanto ci sono altri formati che puoi scegliere per basare le tue docstring. I più popolari sono Epytext, reStructuredText (noto anche come rest), NumPy e Google docstrings. Ciascuno di questi formati ha la propria sintassi, come mostrato negli esempi seguenti:

Epitesto

Una docstring che segue il formato Epytext:

defmoltiplicare(a, b):

 Moltiplica due numeri tra loro.
 @param a: il primo numero da moltiplicare.
 @tipo a: int
 @param b: il secondo numero da moltiplicare.
 @tipo b: int
 @return: il prodotto dei due numeri.
 @rtype: int

ritorno a * b

testo ristrutturato (reST)

Una docstring che segue il formato rest:

defmoltiplicare(a, b):

 Moltiplica due numeri tra loro.
 :param a: Il primo numero da moltiplicare.
 :digitare a: int
 :param b: Il secondo numero da moltiplicare.
 :tipo b: int
 :ritorno: Il prodotto dei due numeri.
 :rtipo: int

ritorno a * b

NumPy

Una docstring che segue il formato NumPy:

defmoltiplicare(a, b):

 Moltiplica due numeri tra loro.
 Parametri

 a: int
 Il primo numero da moltiplicare.
 b: int
 Il secondo numero da moltiplicare.
 ritorna

 int
 Il prodotto dei due numeri.

ritorno a * b

Google

Una docstring che segue il formato Google:

defmoltiplicare(a, b):

 Moltiplica due numeri tra loro.
 Argomenti:
 a (int): il primo numero da moltiplicare.
 b (int): il secondo numero da moltiplicare.
 Ritorna:
 int: il prodotto dei due numeri.

ritorno a * b

Sebbene tutti e quattro i formati docstring forniscano una documentazione utile per la funzione di moltiplicazione, i formati NumPy e Google sono più facili da leggere rispetto ai formati Epytext e reST.

Come includere i test nelle Docstrings

Puoi includere esempi di test nelle tue docstring usando il modulo doctest. Il modulo doctest cerca nella docstring il testo che assomigli a sessioni Python interattive e poi le esegue per verificare che funzionino come dovrebbero.

Per utilizzare i doctest, includi gli input di esempio e gli output previsti nella docstring. Di seguito è riportato un esempio di come lo faresti:

defmoltiplicare(a, b):

 Moltiplica due numeri tra loro.
 Parametri

 a: int
 Il primo numero da moltiplicare.
 b: int
 Il secondo numero da moltiplicare.
 ritorna

 int
 Il prodotto dei due numeri.
 Esempi

 >>> moltiplica(2, 3)
6
 >>> moltiplica(0, 10)
0
 >>> moltiplica(-1, 5)
-5

ritorno a * b

IL Esempi La sezione contiene tre chiamate di funzione con argomenti diversi e specifica l'output previsto per ciascuna. Quando esegui il modulo doctest come mostrato di seguito, eseguirà gli esempi e confronterà l'output effettivo con l'output previsto.

python -m doctest multiply.py

Se ci sono delle differenze, il modulo doctest le riporta come fallimenti. L'uso di doctest con docstring come questo ti aiuta a verificare che il codice funzioni come previsto. Si noti che i doctest non sostituiscono quelli più completi unit test e test di integrazione per il tuo codice Python.

Come generare documentazione da Docstrings

Hai imparato le basi dell'utilizzo di docstring per documentare il tuo codice Python e l'importanza di una documentazione di alta qualità. Per fare un salto di qualità, potresti voler generare la documentazione per i tuoi moduli e funzioni dalle rispettive docstring.

Uno dei generatori di documentazione più popolari che puoi utilizzare è Sphinx. Supporta il formato docstring rest per impostazione predefinita, ma puoi configurarlo per funzionare con il formato Google o NumPy.