Come dovrebbero essere utilizzate le docstring nei moduli con una classe?

Question

Come dovrebbero essere utilizzate le docstring nei moduli con una classe?

#1 da (1 voti)
#2 da (1 voti)

-1

Quando si crea il codice OOP, a volte si ha un file che contiene solo una classe e nient'altro.

PEP8 dice che tutti i moduli e tutte le classi dovrebbero avere docstring che delineano quello che fanno. Ma in questo caso, il modulo è semplicemente un contenitore per la classe. Se inserisci una descrizione della classe, le informazioni vengono duplicate:

"""
Contains a class for connecting to and communicating with a server.
"""

class Client:
    """
    Class for connecting to and communicating with a server.
    """
    def __init__(self):
        ...

Quindi cosa dovrebbe andare nelle docstring? Forse la docstring del modulo dovrebbe dire Contains Foo o qualcosa di simile?

python documentation

posta Omegastick 22.10.2018 - 04:38

fonte

2 risposte

1

Le guide di stile come PEP-8 non sono leggi assolute che devono essere seguite, ma solo guide :

However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!

— PEP 8

Dove un modulo contiene solo una classe, una docstring a livello di modulo non è utile e probabilmente dovresti lasciarla fuori. Se si utilizza un linter che richiede questa superfluo docstring, disabilitare quella politica di linter per il file corrente.

Se leggiamo più attentamente PEP-8, raccomandiamo "docstrings per tutti i moduli pubblici". Un modulo che contiene solo una classe di solito non fa parte dell'interfaccia pubblica, si dovrebbe invece riesportare la classe attraverso un file __init__.py . Ciononostante, una classe per layout di modulo è abbastanza rara in Python. Probabilmente avrai funzioni di supporto non pubbliche o altre classi strettamente correlate nello stesso file.

risposta data 22.10.2018 - 11:13

fonte

Leggi altre domande sui tag python documentation

Come utilizzare le richieste pull per le revisioni del codice con un repository remoto condiviso? E 'richiesto di rivelare il codice sorgente per il software Qt personalizzato? [chiuso]

score 1 · Accepted Answer

When authoring OOP code, it is very common to have a file that only contains one class, and nothing else.

Questo è comune in alcune lingue e può essere applicato, come in Java. Tuttavia, ha molto poco a che fare con OOP e più a che fare con il fatto che Java è un linguaggio OOP popolare. Scrivo / modifico diverse classi in un singolo file ogni giorno (sono un dev di Python), è una pratica abbastanza comune.

PEP8 says that all modules and all classes should have docstrings outlining what they do. But in this case, the module is simply a container for the class. If you put a description of the class, then the information is duplicated

Sì, sarebbe duplicato se stai seguendo una regola di una classe per file. Hai alcune scelte:

Smetti di seguire la regola e consenti più classi per file (specialmente se la segui solo perché è una best practice percepita)
Inserisci la docstring nella classe e dimentica la docstring del livello del modulo. Se è solo una classe per modulo (e segui rigorosamente OOP), allora tutto sarà nella classe, quindi la docstring del modulo sarà abbastanza priva di significato. È perfettamente accettabile non seguire PEP8 alla lettera e, in generale, è meglio fare solo ciò che è meglio per la tua situazione particolare rispetto a seguire in modo cieco / dogmatico uno standard o una buona pratica.

HTH.

P.S. Se un linter si lamenta, e questo a sua volta sta rovinando le tue build, di solito ci sono opzioni per disattivare determinati requisiti PEP8. Ad esempio, ignorare E501 (lunghezza della linea superiore a 80 caratteri) è comune a quanto vedo che i team scelgono di ignorare (se il modulo pep8 è il tuo linter, puoi fare pep8 --ignore=E501 , ad esempio)