CKTIS / Python
docstring — stringa di documentazione
Un docstring è un normale letterale di stringa (né una f-string né una t-string), usato come prima istruzione di un modulo, una classe o una funzione. Documenta lo scopo dell’oggetto ed è accessibile tramite __doc__; non è un commento che inizia con #.
Versione: Python 3.14; repository image, production runtime not attested
Sintassi
def function_name():
"""Describe the function's purpose."""
passUn docstring è un normale letterale di stringa (né una f-string né una t-string), collocato come prima istruzione di un modulo, di una classe o di una funzione, compresi i metodi. Python lo rende disponibile come attributo __doc__ dell’oggetto. Gli strumenti possono usare questo contenuto per mostrare la documentazione.
Né un letterale di stringa formattata (f-string) né un letterale di stringa modello (t-string) crea un docstring, anche se il letterale non contiene campi di sostituzione ed è la prima istruzione. Se la prima istruzione di una funzione è f"""Description.""", il suo attributo __doc__ vale None.
Un commento che inizia con # non crea un docstring. Anche un letterale di stringa autonomo collocato dopo un’altra istruzione non diventa il docstring principale dell’oggetto. Le virgolette triple """...""" sono comode, soprattutto per più righe, ma non bastano da sole: contano sia il tipo di letterale sia la sua posizione.
Per convenzione, la prima riga dovrebbe descrivere brevemente lo scopo dell’oggetto, iniziare con una lettera maiuscola e terminare con un punto. Separa la descrizione aggiuntiva con una riga vuota; quando serve, spiega gli argomenti, i risultati e gli effetti collaterali. Sono indicazioni sul contenuto, non requisiti sintattici.
Nell’esempio, square.__doc__ rende accessibile la descrizione, mentre square(5) calcola il risultato indipendentemente dalla documentazione. L’opzione -OO rimuove i docstring, quindi il codice dell’applicazione non dovrebbe dipendere dalla loro presenza.
Esempi
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Risultato
Return the square of number. 25
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.