Beim Schreiben von Doc-Strings in Python frage ich mich, ob der Docstring die Exceptions enthalten soll, die implizit ausgelöst werden oder ob er auch die Exceptions enthalten soll, die ich explizit aufrufe.
Betrachten Sie die Funktion
%Vor%Also würde ich in einem Docstring unter dem Schlüsselwort "Raises" ZeroDivisionError setzen. Abhängig von der Eingabe würde ich aber auch einen TypeError erwarten. Würdest du das auch in den Docstring legen?
Aufgrund des EAFP-Prinzips (wenn ich es richtig verstehe) möchte ich hier nicht nach Typen suchen, richtig? Jeder Hinweis (auch auf das Codebeispiel) ist willkommen.
Es hängt davon ab, für wen Sie den Docstring schreiben. Für die automatische Konvertierung in die API-Dokumentation mag ich Google-Stil-Docstrings , die folgendermaßen aussehen würden:
%Vor% Hier habe ich alle Ausnahmen eingeschlossen, die die Funktion wahrscheinlich auslösen wird . Beachten Sie, dass Sie raise ZeroDivisionError
nicht explizit angeben müssen - dies geschieht automatisch, wenn Sie versuchen, durch Null zu teilen.
Wenn Sie jedoch keine Dokumentation über den Docstring erstellen, würde ich wahrscheinlich nur die Beschreibungszeile für eine solche einfache Funktion einfügen:
%Vor%Jeder, der es benutzt, wird wahrscheinlich wissen, dass Sie z.B. Zeichenfolgen.
Ich möchte hier nicht nach Typen suchen, richtig?
Ich würde nicht - wenn der Benutzer nach dem Lesen Ihrer Dokumentation beschließt, z.B. eine Zeichenfolge in die Funktion, die erwartet sollte TypeError
erhalten, und es hat keinen Sinn, den Argumenttyp zu testen, um dann die selbe Exception selbst auszulösen, die der Code sowieso erhöht hätte (siehe auch die ZeroDivisionError
!) Das heißt, außer zB float
oder complex
Zahlen sollten ungültige Eingabe sein, in diesem Fall müssen Sie sie manuell behandeln.
Nein. Der Docstring sollte die erwartete Eingabe beschreiben. Wenn dies meine Funktion wäre, würde ich so etwas in den Docstring aufnehmen:
%Vor% Daher wird angegeben, dass die Eingabe eine ganze Zahl sein soll. Die Angabe, dass die Funktion TypeError
erhöhen kann, erschwert den Docstring nur zu sehr.
Tags und Links python python-3.x docstring raise