Ho visto alcuni stili diversi di scrivere dotstrings in Python, esiste uno stile ufficiale o "concordato"?

formati

I docstring di Python possono essere scritti seguendo diversi formati, come mostrato dagli altri post. Tuttavia, il formato di dotstring predefinito Sphinx non è stato menzionato ed è basato su reStructuredText (reST) . Puoi ottenere alcune informazioni sui principali formati in questo post del blog .

Si noti che il reST è raccomandato dal PEP 287

Segue i principali formati utilizzati per i docstring.

- Epytext

Storicamente uno stile javadoc era prevalente, quindi è stato preso come base per Epydoc (con il Epytextformato chiamato ) per generare documentazione.

Esempio:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- riposo

Al giorno d'oggi, il formato probabilmente più diffuso è il formato reStructuredText (reST) utilizzato da Sphinx per generare documentazione. Nota: viene utilizzato per impostazione predefinita in JetBrains PyCharm (digitare virgolette triple dopo aver definito un metodo e premere invio). Viene anche utilizzato di default come formato di output in Pyment.

Esempio:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google ha il suo formato che viene spesso utilizzato. Può anche essere interpretato da Sphinx (cioè usando il plugin Napoleon ).

Esempio:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Ancora più esempi

- Numpydoc

Nota che Numpy consiglia di seguire il proprio numpydoc basato sul formato di Google e utilizzabile da Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Conversione / Generazione

È possibile utilizzare uno strumento come Pyment per generare automaticamente docstring in un progetto Python non ancora documentato, o convertire i dotstring esistenti (possono mescolare diversi formati) da un formato a un altro.

Nota: gli esempi sono tratti dalla documentazione di Pyment

La guida di stile di Google contiene un'eccellente guida di stile di Python. Include convenzioni per la sintassi di docstring leggibile che offre una guida migliore rispetto a PEP-257. Per esempio:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Mi piace estenderlo per includere anche informazioni sul tipo negli argomenti, come descritto in questo tutorial sulla documentazione di Sphinx . Per esempio:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Le convenzioni di Docstring sono in PEP-257 con molti più dettagli di PEP-8.

Tuttavia, le dotstring sembrano essere molto più personali di altre aree di codice. Diversi progetti avranno il loro standard.

Tendo a includere sempre i docstring, perché tendono a dimostrare come utilizzare la funzione e cosa fa molto rapidamente.

Preferisco mantenere le cose coerenti, indipendentemente dalla lunghezza della stringa. Mi piace l'aspetto del codice quando rientro e spaziatura sono coerenti. Ciò significa che io uso:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Al di sopra di:

def sq(n):
    """Returns the square of n."""
    return n * n

E tende a smettere di commentare la prima riga in docstrings più lunghi:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Significato: trovo che le dotstring che iniziano in questo modo siano disordinate.

def sq(n):
    """Return the squared result. 
    ...

Come apparentemente nessuno lo ha menzionato: puoi anche usare lo standard Numpy Docstring . È ampiamente usato nella comunità scientifica.

• La specifica del formato da numpy insieme a un esempio
• Hai un'estensione sfinge per renderlo: numpydoc
• E un esempio di come può apparire bella una docstring renderizzata: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

L'estensione della sfinge napoletana per analizzare i docstring in stile Google (consigliata nella risposta di @Nathan) supporta anche il docstring in stile Numpy e fa un breve confronto di entrambi.

E infine un esempio di base per dare un'idea di come appare:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 è lo standard ufficiale di codifica Python. Contiene una sezione su dotstrings, che fa riferimento a PEP-257 - una specifica completa per docstrings.

È Python; tutto va bene . Valuta come pubblicare la tua documentazione . Docstrings sono invisibili ad eccezione dei lettori del tuo codice sorgente.

Alla gente piace molto navigare e cercare documentazione sul web. Per farlo, usa lo strumento di documentazione Sphinx . È lo standard di fatto per la documentazione di progetti Python. Il prodotto è bellissimo: dai un'occhiata a https://python-guide.readthedocs.org/en/latest/ . Il sito web Leggi i documenti ospiterà i tuoi documenti gratuitamente.

Io suggerisco di usare di Vladimir Keleshev pep257 programma Python per controllare i docstrings contro PEP-257 e il Numpy docstring standard per la descrizione dei parametri, i rendimenti, ecc

pep257 segnalerà la divergenza che si fa dallo standard e si chiama come pylint e pep8.