Gibt es einen Konsens, was in den Klassen und __init__ Docstrings dokumentiert werden sollte?

Question

Ich fand keine Best Practice darüber, was in den Klassen und __init__ Docstrings dokumentiert werden sollte. Manchmal finde ich, dass die Konstruktorargumente bereits in den Klassen Docstring dokumentiert sind, manchmal sind sie im Docstring __init__ beschrieben. Ich bevorzuge es, die Konstruktion innerhalb der Klassen Docstring zu beschreiben, da dies beim Erstellen einer neuen Instanz aufgerufen wird. Aber was sollte dann in den __init__ Methoden Docstring dokumentiert werden?

---

edit:

Ich weiß um die google styleguide und die google docstring style example, aber beide nicht meine Frage beantworten. Das docstring Stil Beispiel sagt

Die __init__ Methode docstring entweder in der Klassenstufe dokumentiert werden kann, oder als docstring auf der __init__ Methode selbst. Entweder Form ist akzeptabel, aber die beiden sollten nicht gemischt werden. Wählen Sie eine Konvention, um die __init__ Methode zu dokumentieren und konsistent zu sein.

Aber wenn ich wählen Sie die docstring der __init__ Funktion in die Klasse Ebene docstring setzen, was soll das __init__ docstring enthalten?

Answer 1

ich persönlich versuchen, die google styleguide wenn möglich

zu verwenden, wenn Sie eine neue Instanz mit __init__ schaffen es dokumentiert werden soll, welche Membervariablen initialisiert werden. Dann wissen andere, was sie erwarten können, wenn sie später in ihrem Code auf sie zugreifen müssen.

Probe aus dem Styleguide google:

class SampleClass(object): 
    """Summary of class here. 

    Longer class information.... 
    Longer class information.... 

    Attributes: 
     likes_spam: A boolean indicating if we like SPAM or not. 
     eggs: An integer count of the eggs we have laid. 
    """ 

    def __init__(self, likes_spam=False): 
     """Inits SampleClass with blah.""" 
     self.likes_spam = likes_spam 
     self.eggs = 0 

    def public_method(self): 
     """Performs operation blah.""" 

Answer 2

Google ihre eigenen Styleguide für Python hat, die nicht eine schlechte Sache zu beziehen. Hier ist ein Link zu dem, was sie als Best Practices für Doc-Strings betrachten: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

Answer 3

Mir ist kein Konsens in diesem Punkt bekannt.

jedoch das sphinx autodoc Modul ermöglicht Dokumentation von Ihrem docstring erzeugt werden Folglich neigt sie dazu, im Einklang docstring Dokumentation zu erzwingen.

In Ihrem Fall würde ich dokumentieren, was die class ist und die Konstruktorargumente im classdocstring wie:

class MyClass: 
    """I am a class. 
    I do funny stuff 

    :type tags: dict 
    :param tags: A dictionary of key-value pairs 
    """ 

    def __init__(tags): 
     self.tags = tags