Ich füge eine ( epydoc ) Dokumentation zu einem Paket hinzu, das ich geschrieben habe, und ich bin es auch Ich begegne vielen Fällen, in denen ich mich viele Male wiederhole.
%Vor%PEP257 sagt Folgendes:
One-Liner sind für wirklich offensichtliche Fälle.
und auch
Der Docstring für eine Funktion oder Methode sollte sein Verhalten zusammenfassen und seine Argumente, Rückgabewert (e), Nebeneffekte, ausgelöste Ausnahmen und Einschränkungen beim Aufruf (falls zutreffend) dokumentieren.
Gibt es eine allgemeine Richtlinie oder Standardpraxis, wann die Grenze zwischen einem Einzeiler (Beschreibung) und einem vollständigen Parameter / Rückgabefeld gezogen werden sollte?
Oder wenn ich Dokumentation erzeuge, sollte ich jedes anwendbare Feld für jede Funktion angeben, egal wie wiederholend es scheint?
Bonusfrage: Syntaktisch, wie beschreibt man script param am besten?
Die allgemeine Richtlinie, nach der Sie suchen, ist richtig in PEP257 in dem, was Sie zitiert haben, vielleicht Sie muss es nur in Aktion sehen.
Ihre Funktion ist ein guter Kandidat für einen einzeiligen Docstring ( "wirklich offensichtliche Fälle" ):
%Vor% Wenn Sie normalerweise sagen, dass eine Funktion etwas überprüft, bedeutet das, dass sie True oder False zurückgibt, aber wenn Sie möchten, könnten Sie spezifischer sein:
Noch einmal alles in einer Zeile.
Ich würde wahrscheinlich auch den Namen Ihrer Funktion ändern, weil Sie nicht betonen müssen, wie die Funktion in ihrem Namen funktioniert (ein Skript). Ein Funktionsname sollte etwas Süßes, Kurzes und Bedeutungsvolles über die Funktion sein. Wahrscheinlich werde ich mit gehen:
%Vor%Manchmal ist die funktion-name-imagination durch all die Codierung müde, aber Sie sollten trotzdem versuchen, Ihr Bestes zu geben.
Lassen Sie mich für ein Beispiel mit mehreren Zeilen einen Docstring aus den Google-Richtlinien
Dies könnte eine Möglichkeit sein, sein Verhalten zusammenzufassen und seine Argumente, Rückgabewerte, Nebeneffekte, aufgetretenen Ausnahmen und Einschränkungen, wann es aufgerufen werden kann (falls zutreffend) zu dokumentieren. .
Vielleicht interessiert Sie auch das Beispiel eines Pypi-Projekts , das es ist soll mit Sphinx dokumentiert werden.
Meine 2 Cent: Richtlinien sollen Ihnen eine Vorstellung davon geben, was Sie tun sollten und was nicht, aber sie sind keine strengen Regeln, die Sie blind befolgen müssen Folgen. Wähle am Ende, was du besser findest.
Ich möchte etwas, das in einer anderen Antwort gesagt wurde, über die Maximale Zeilenlänge mit einem Docstring sagen.
PEP8 sagt zu "Begrenzen Sie alle Zeilen auf maximal 79 Zeichen" obwohl am Ende jeder 80 macht.
Dies sind 80 Zeichen:
%Vor%Und das könnte ein Randfall sein, in dem nur ein langer Satz ausreicht:
%Vor%Ist wie ein einzeiliger Docstring, dh für wirklich offensichtliche Fälle , aber auf Ihrem Editor (mit der 80 Zeichen Grenze) ist in mehreren Zeilen.
Ich denke, es ist wahrscheinlich immer ein gewisses Maß an Wiederholung beteiligt, wenn erweiterte Syntax für Docstrings hinzugefügt wird, d. h. epydoc / sphinx markup.
Ich würde auch sagen, dass diese Frage subjektiver als objektiver ist. Explizit ist besser als implizit und scheint dem Zen von Python mehr zu folgen.
Tags und Links python documentation docstring