Auf der einen Seite werden wir ermutigt, Felder zu erstellen und unsere Python-Klassen nicht mit zusätzlichen Accessor-Funktionen zu versehen, die anderen Sprachen nachempfunden sind.
Andererseits wurde die PEP für 'Attribut-Docstrings' abgelehnt.
>Auf der dritten Seite, epydoc und sphinx unterstützt sie. Auf die Gefahr einer nicht-konstruktiven Frage hin gibt es eine einzige, eindeutige, übliche Praxis für die Dokumentation von Variablen in Klassen?
Ich formuliere meinen Kommentar als Antwort, da ich dazu aufgefordert wurde.
Allgemein (öffentliche) Attribute der Instanz sind selbsterklärend und ihre Verwendung durch den Benutzer erfordert keine Dokumentation. Der Name des Attributs und der Kontext reichen aus, um zu verdeutlichen, was das Attribut ist, und Sie können in der -Klassendokumentation ein wenig Dokumentation darüber einfügen, wie Sie damit umgehen.
Unter bestimmten Umständen möchten Sie dem Benutzer den Zugriff auf ein Attribut gewähren, aber das Attribut ist nicht selbsterklärend genug und / oder seine Handhabung erfordert Aufmerksamkeit (denn wenn es nicht richtig gehandhabt wird, könnte es "blasen" Dinge auf ").
Zum Beispiel möchten Sie vielleicht den Benutzer wissen lassen, dass ein Attribut eine bestimmte "Schnittstelle" haben sollte, damit es verwendet werden kann. Oder Sie müssen eine Bedingung erklären, die das Attribut erfüllen muss.
In diesem Fall ist es keine gute Idee, die Dokumentation mit dem Dokument der Klasse zusammenzustellen, da die Dokumentation der Klasse immer länger wird und eine Menge wirklich spezifisches Wissen erklärt.
Die einfache und, ich denke, elegantere Lösung besteht darin, Eigenschaften zu verwenden. Mit den Eigenschaften können Sie dem Attribut und einen Docstring hinzufügen, mit dem Sie den Zugriff darauf effektiv steuern können. Dadurch wird die Klasse robuster.
Wenn Sie mit vielen Attributen umgehen müssen, ist es vielleicht schwierig, Dutzende von Eigenschaften zu schreiben, aber Sie können sie immer noch dynamisch hinzufügen, zum Beispiel mit einem Dekorator. Dies funktioniert besonders gut, wenn Sie nur einen Docstring hinzufügen möchten, indem Sie immer die gleiche Art von Getter / Setter verwenden.
Zum Beispiel könnten Sie schreiben:
%Vor%Und benutze es so:
%Vor%In einem Kommentar wies Lukas Graf darauf hin, dass Sie mit Zope.interface eine Klasse erstellen können, die einfach die konkrete Klasse beschreibt, die Ihnen die Möglichkeit gibt, den Eigenschaften Docstrings hinzuzufügen. Dies wäre wahrscheinlich eine andere Option. Ich habe keine Erfahrung in der Verwendung von Zope.interface, so dass ich nicht genau sagen kann, was Sie tun können und wie und wie es letztlich mit Auto-Dokumentationsprogrammen interagiert.
Tags und Links python