Come scrivere dotstrings significativi?

Question

Cos'è, secondo te, una dottrina significativa? Cosa ti aspetti di essere descritto lì?

Ad esempio, considera il __init__ di questa classe Python:

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
    """

Lo trovi significativo? Pubblica i tuoi esempi positivi / negativi che tutti possono sapere (e una risposta generale in modo che possa essere accettata).

Answer 1

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

Potresti anche voler utilizzare Sphinx (e sintassi reStructuredText) a scopo di documentazione all'interno dei tuoi documenti. In questo modo puoi includerlo facilmente nella tua documentazione. Per un esempio, controlla ad es. repoze.bfg che lo utilizza ampiamente ( file di esempio , esempio di documentazione ).

Un'altra cosa che si può mettere nei docstrings è anche doctest . Questo potrebbe avere senso esp. per i docstring del modulo o della classe, come puoi anche mostrare in questo modo come usarlo e avere questo test allo stesso tempo.

Answer 2

Da PEP 8 :

  

Convenzioni per scrivere buone stringhe di documentazione (a.k.a.   " docstrings ") sono immortalati in PEP 257 .

     

  
• Scrivi docstring per tutti i moduli, funzioni, classi e metodi pubblici. Docstrings non sono necessari per metodi non pubblici, ma tu   dovrebbe avere un commento che descriva cosa fa il metodo. Questo   il commento dovrebbe apparire dopo la "quot" def " linea.
  
• PEP 257 descrive buone convenzioni di dotstring. Nota che, soprattutto, il "quot" " " che termina una dotstring multilinea dovrebbe essere su a   riga da sola e preferibilmente preceduta da una riga vuota.
  
• Per le dotstring di una riga, è bene mantenere la chiusura "quot" " " sulla stessa riga.
  

Answer 3

Cosa dovrebbe andare lì:

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

Answer 4

Consulta i documenti di Numpy per buoni esempi (ad esempio http: / /github.com/numpy/numpy/blob/master/numpy/core/numeric.py ).

I docstring sono divisi in diverse sezioni e si presentano così:

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 5

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

Un'altra cosa utile che puoi inserire nei tuoi documenti è un doctest .

Answer 6

Mi piace usare la documentazione per descrivere nel modo più dettagliato possibile cosa fa la funzione, in particolare il comportamento in casi d'angolo (a.k.a. casi limite). Idealmente, un programmatore che utilizza la funzione non dovrebbe mai guardare il codice sorgente - in pratica, ciò 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 in una stringa di documentazione.

Answer 7

Lo scopo generale dell'aggiunta di una stringa doc all'inizio della funzione è quello di descrivere la funzione, cosa fa, cosa restituisce e la descrizione dei parametri. È possibile aggiungere dettagli di implementazione, se necessario. Anche tu puoi aggiungere dettagli sull'autore che ha scritto il codice per il futuro sviluppatore.