Cosa mettere in un docstring del modulo Python? [chiuso]

167

Ok, quindi ho letto sia PEP 8 che PEP 257 e ho scritto un sacco di docstring per funzioni e classi, ma non sono sicuro di cosa dovrebbe andare in un docstring del modulo. Ho pensato, come minimo, che dovrebbe documentare le funzioni e le classi che il modulo esporta, ma ho anche visto alcuni moduli che elencano i nomi degli autori, le informazioni sul copyright, ecc. Qualcuno ha un esempio di come dovrebbe essere un buon dotstring di Python essere strutturato?

python documentation module

Risposte:

183

Pensa a qualcuno che fa help(yourmodule)al prompt dell'interprete interattivo: cosa vogliono sapere? (Altri metodi di estrazione e visualizzazione delle informazioni sono approssimativamente equivalenti a helpin termini di quantità di informazioni). Quindi se hai in x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

poi:

>>> import x; help(x)

Spettacoli:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

Come vedi, le informazioni dettagliate sulle classi (e anche sulle funzioni, anche se non ne sto mostrando una qui) sono già incluse nelle dotstring di quei componenti; la stessa dotstring del modulo dovrebbe descriverli in modo molto sommario (se non del tutto) e piuttosto concentrarsi su un breve riassunto di ciò che il modulo nel suo insieme può fare per te, idealmente con alcuni esempi documentati (proprio come idealmente funzioni e classi dovrebbero avere esempi documentati in loro dotstrings).

Non vedo come metadati come nome dell'autore e copyright / licenza aiutino l'utente del modulo - può piuttosto andare nei commenti, dal momento che potrebbe aiutare qualcuno a considerare se riutilizzare o modificare il modulo.

— Alex Martelli
fonte

Quindi, è consuetudine includere autore, copyright, ecc. Nei commenti nella parte superiore di un modulo?

@ 007brendan, è pratica abbastanza comune, sì.

— Alex Martelli

@IfLoop Dubito che ci siano più utenti che usano il help()metodo nell'interprete rispetto agli utenti che leggono semplicemente il codice.

— confuso il

Ricorda, la cosa più importante da documentare è il perché . Documentare cosa fa qualcosa è il lavoro di un codice ben scritto. Documentare perché è il lavoro della documentazione.

— Erik Aronesty,

Per citare le specifiche :

Il docstring di uno script (un programma autonomo) dovrebbe essere utilizzabile come messaggio di "utilizzo", stampato quando lo script viene invocato con argomenti errati o mancanti (o forse con un'opzione "-h", per "aiuto"). Tale docstring dovrebbe documentare la funzione dello script e la sintassi della riga di comando, le variabili di ambiente e i file. I messaggi di utilizzo possono essere abbastanza elaborati (diverse schermate piene) e dovrebbero essere sufficienti per un nuovo utente per utilizzare correttamente il comando, nonché un rapido riferimento completo a tutte le opzioni e argomenti per l'utente sofisticato.

La documentazione per un modulo dovrebbe generalmente elencare le classi, le eccezioni e le funzioni (e qualsiasi altro oggetto) che vengono esportate dal modulo, con un sommario di una riga di ciascuno. (Questi riepiloghi in genere forniscono meno dettagli della riga di riepilogo nella documentazione dell'oggetto.) La documentazione per un pacchetto (ovvero la documentazione del __init__.pymodulo del pacchetto ) dovrebbe anche elencare i moduli e i pacchetti secondari esportati dal pacchetto.

La documentazione per una classe dovrebbe riassumere il suo comportamento ed elencare i metodi pubblici e le variabili di istanza. Se la classe deve essere sottoclassata e ha un'interfaccia aggiuntiva per le sottoclassi, questa interfaccia deve essere elencata separatamente (nella documentazione). Il costruttore della classe deve essere documentato nella documentazione per il suo __init__metodo. I singoli metodi dovrebbero essere documentati con la propria dotstring.

Il docstring di una funzione o metodo è una frase che termina in un punto. Prescrive l'effetto della funzione o del metodo come comando ("Fai questo", "Restituiscilo"), non come descrizione; ad es. non scrivere "Restituisce il nome percorso ...". Un docstring su più righe per una funzione o un metodo dovrebbe riassumere il suo comportamento e documentare i suoi argomenti, i valori di ritorno, gli effetti collaterali, le eccezioni sollevate e le restrizioni su quando può essere chiamato (tutto se applicabile). Argomenti opzionali dovrebbero essere indicati. Dovrebbe essere documentato se gli argomenti di parole chiave fanno parte dell'interfaccia.

— Remi
fonte