Come scrivere docstrings significativi?

Question

Cosa, secondo te, è una docense significativa? Cosa ti aspetti di essere descritto lì?

Si consideri ad esempio di questa classe Python __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"): 
    """ 
    name - field name 
    value - field value 
    displayName - nice display name, if empty will be set to field name 
    matchingRule - I have no idea what this does, set to strict by default 
    """ 

Trovi questo significativo? Pubblica i tuoi buoni/cattivi esempi per tutti da sapere (e una risposta generale in modo che possa essere accettata).

Answer 1

Sono d'accordo con "Tutto ciò che non si può dire dalla firma del metodo". Potrebbe anche significare spiegare cosa restituisce un metodo/funzione.

Si potrebbe anche voler usare Sphinx (e la sintassi reStructuredText) a scopo di documentazione all'interno delle proprie docstring. In questo modo puoi includere facilmente questo nella tua documentazione. Per un esempio, controlla ad es. repoze.bfg che utilizza questo ampiamente (example file, documentation example).

Un'altra cosa che è possibile inserire nelle docstring è anche doctests. Questo potrebbe aver senso per docstring di modulo o classe, come puoi anche mostrare in che modo usarlo e farlo testabile allo stesso tempo.

Answer 2

Che cosa dovrebbe andare lì:

Tutto ciò che non si può dire dalla firma del metodo. In questo caso l'unico bit utile è: displayName - se vuoto verrà impostato sul nome del campo.

Answer 3

Mi piace utilizzare la documentazione per descrivere nel modo più dettagliato possibile ciò che fa la funzione, in particolare il comportamento nei casi d'angolo (a.k.a. casi limite). Idealmente, un programmatore che usa la funzione non dovrebbe mai guardare il codice sorgente - in pratica, questo significa che ogni volta che un altro programmatore deve guardare il codice sorgente per capire alcuni dettagli su come funziona la funzione, quel dettaglio probabilmente avrebbe dovuto essere menzionato nella documentazione. Come ha detto Freddy, tutto ciò che non aggiunge alcun dettaglio alla firma del metodo probabilmente non dovrebbe essere contenuto in una stringa di documentazione.

Answer 4

Le cose più sorprendenti che posso pensare di includere in una docstring sono le cose che non sono ovvie. Di solito questo include informazioni sul tipo o requisiti di capacità - es. "Richiede un oggetto simile a un file". In alcuni casi questo sarà evidente dalla firma, non così in altri casi.

Un'altra utile cosa che è possibile aggiungere alle proprie docstring è doctest.

Answer 5

Da PEP 8:

convenzioni per la scrittura stringhe di documentazione (pseudonimo "docstring") sono immortalati in PEP 257.

• Scrivere docstrings per tutti i moduli pubblici, funzioni, classi e metodi. Le didascalie non sono necessarie per i metodi non pubblici, ma è necessario un commento che descriva il metodo. Questo commento dovrebbe apparire dopo la riga "def".
• PEP 257 descrive le convenzioni di buona documentazione. Nota che, soprattutto, il "" "che termina una docstring su più righe dovrebbe essere su una riga da solo e preferibilmente preceduto da una riga vuota.
• Per docstrings uno di linea, va bene per mantenere la chiusura """ sulla stessa linea. Docstrings

Answer 6

Partenza di NumPy per i buoni esempi (ad es http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

I docstrings sono divisi in varie sezioni e simile a questa:

Compute the sum of the elements of a list. 

Parameters 
---------- 
foo: sequence of ints 
    The list of integers to sum up. 

Returns 
------- 
res: int 
    sum of elements of foo 

See also 
-------- 
cumsum: compute cumulative sum of elemenents 

Answer 7

Generalmente scopo di aggiungere l'aggiunta di stringa doc in partenza della funzione è quello di descrivere la funzione, che cosa fa, wha t ritornerebbe e descrizione dei parametri. È possibile aggiungere dettagli di implementazione, se necessario. Anche tu puoi aggiungere dettagli sull'autore che ha scritto il codice per lo sviluppatore futuro.