Docstring
Nella programmazione una docstring è un letterale di tipo stringa inserito nel codice sorgente che ha la funzione, analogamente ad un commento, di documentare una porzione di codice. A differenza dei commenti, in testo semplice o con una formattazione particolare come javadoc o doxygen, che vengono ignorati dal parser del compilatore o dell'interprete, le docstring vengono conservate e sono disponibili a runtime, semplificando l'ispezione del codice e fornendo aiuto o metadati durante l'esecuzione.
Tra i linguaggi che supportano le docstring vi sono Python, Lisp, Elixir e Clojure.[1]
Esempi
Elixir
Le docstring sono usate in Elixir per la documentazione, e il linguaggio di markup usato come standard de facto è il markdown:
defmodule MyModule do
@moduledoc """
Documentazione del modulo, con **formattazione** markdown.
"""
@doc "Hello"
def world do
"World"
end
end
Lisp
In Lisp, le docstring sono chiamate stringhe di documentazione (documentation strings). Lo standard del Common Lisp stabilisce che le implementazioni possono liberamente ignorare le docstring. Quando esse vengono conservate, possono essere ispezionate e modificate usando la funzione DOCUMENTATION.[2]
(defun foo () "questa è una docstring" nil)
(documentation #'foo 'function) => "questa è una docstring"
Python
Le docstring in Python vengono usate per documentare il codice e sono inserite come prima istruzione che segue la definizione di funzioni, metodi, moduli e classi, mentre se inserite altrove vengono ignorate. Le docstring sono racchiuse tra tripli apici doppi, e possono contenere interruzioni di riga. Si può accedere alle docstring tramite l'attributo __doc__ di un oggetto. Le linee guida sull'uso delle docstring sono raccolte nella PEP 257 (Python Enhancement Proposal), di livello Informative. Se la docstring è su una sola riga si raccomanda di avere gli apici di apertura e di chiusura sulla stessa riga, mentre se è su più righe si raccomanda di avere un brief sulla stessa riga degli apici di apertura, seguito dai dettagli dopo un salto di riga, e gli apici di chiusura su una nuova riga.[3]
"""programma.py
Questa docstring all'inizio del file viene riconosciuta.
"""
class MyClass(object):
"""Docstring della classe.
Dettagli della classe.
"""
def my_method(self):
"""Docstring del metodo."""
def my_function():
"""Docstring della funzione."""
Si può accedere alle docstring in una sessione interattiva dell'interprete:
>>> import mymodule
>>> help(mymodule)
programma.py
Questa docstring all'inizio del file viene riconosciuta.
>>> help(mymodule.MyClass)
Docstring della classe.
Dettagli della classe.
>>> help(mymodule.MyClass.my_method)
Docstring del metodo.
>>> help(mymodule.my_function)
Docstring della funzione.
>>>
La docstring di uno script deve essere usabile come messaggio all'utente, documentandone uso, parametri e sintassi in modo dettagliato. La docstring di un modulo elenca usualmente classi, eccezioni e funzioni esportate dal modulo, con una riga di spiegazione per ognuno dei componenti. Quella di un package usualmente riporta anche moduli e subpackage esportati dal package. La docstring di un metodo è tipicamente una frase di un solo periodo che riporta in maniera coincisa l'effetto ("Fa x", "Restituisce y"), senza dilungarsi in descrizioni, oppure può essere una docstring multilinea che dopo una riga di descrizione sommaria riporta i dettagli di tutti i parametri (anche opzionali), valori restituiti, effetti collaterali, eccezioni e restrizioni d'uso. La docstring di una classe riassume il comportamento della stessa e usualmente elenca i metodi e gli attributi, eventuali interfacce per sottoclassi. Il costruttore e i metodi dovrebbero essere documentati in dettaglio nelle relative docstring.
Voci correlate
Note
Collegamenti esterni
- Python Docstrings
- Documentazione in GNU Emacs Lisp
- Sezione sulle docstring nella documentazione di doxygen
