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]

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

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"

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.

La già citata PEP 257 non specifica un formato particolare per la documentazione. Vari formati sono di uso comune, a seconda delle convenzioni o dagli strumenti di generazione automatica della documentazione adottati nei progetti da documentare. Seguono degli esempi di docstring a documentazione di una funzione con alcuni dei principali formati comunemente usati.

Epydoc supporta un formato mutuato da javadoc:^[4]

""" Brief

Descrizione...

@param p1: descrizione del primo parametro p1
@param p2: descrizione del secondo parametro p2
@return: descrizione del valore di ritorno della funzione
@raise Exception: descrizione dell'eccezione lanciata
"""

Epydoc e Sphinx supportano il formato reStructuredText (reST):^[5]

""" Brief

Descrizione...

:param p1: descrizione del primo parametro p1
:param p2: descrizione del secondo parametro p2
:returns: descrizione del valore di ritorno della funzione
:raises Exception: descrizione dell'eccezione lanciata
"""

Le convenzioni stilistiche di Google specificano un loro formato, usato nei progetti in Python di Google e piuttosto diffuso anche altrove, che è anche leggibile da Sphinx^[6]:

""" Brief

Descrizione...

Args:
    p1 : descrizione del primo parametro p1
    p2 : descrizione del secondo parametro p2

Returns:
    Descrizione del valore di ritorno

Raises:
    Exception : descrizione dell'eccezione lanciata
"""

NumPy ha un suo formato di docstring mutuato dal formato Google, leggibile da Sphinx.

""" Brief

Descrizione...

Parameters
----------
p1 : tipo
    descrizione del primo parametro p1
p2 : tipo
    descrizione del secondo parametro p2
p3 : tipo, optional
    descrizione del terzo parametro opzionale p3

Returns
-------
tipo
    descrizione del tipo di ritorno

Raises
------
Exception
    descrizione dell'eccezione lanciata
"""

• Literate programming
• Plain Old Documentation

• Python Docstrings, su epydoc.sourceforge.net.
• Documentazione in GNU Emacs Lisp, su linuxselfhelp.com. URL consultato il 18 aprile 2015 (archiviato dall'url originale il 3 marzo 2016).
• Sezione sulle docstring nella documentazione di doxygen

Portale Informatica: accedi alle voci di Teknopedia che trattano di informatica