Wie schreibe ich sinnvolle Docstrings?

Was, Ihrer Meinung nach, ist ein sinnvoller Docstring? Was erwarten Sie dort beschrieben zu werden?Wie schreibe ich sinnvolle Docstrings?

Betrachten wir zum Beispiel diese Python Klasse __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"): 
    """ 
    name - field name 
    value - field value 
    displayName - nice display name, if empty will be set to field name 
    matchingRule - I have no idea what this does, set to strict by default 
    """

Sie das für sinnvoll halten Sie? Posten Sie Ihre guten/schlechten Beispiele für alle (und eine allgemeine Antwort, damit sie akzeptiert werden).

Quelle

2009-03-02 Konrads

Ich stimme zu "Alles, was Sie nicht von der Signatur der Methode unterscheiden können". Es könnte auch bedeuten zu erklären, was eine Methode/Funktion zurückgibt.

Sie könnten auch Sphinx (und die reStructuredText-Syntax) zu Dokumentationszwecken in Ihren Docstrings verwenden. Auf diese Weise können Sie dies problemlos in Ihre Dokumentation aufnehmen. Für ein Beispiel Auschecken z.B. repoze.bfg, die dies umfassend verwendet (example file, documentation example).

Eine andere Sache, die man in Docstrings setzen kann, ist auch doctests. Dies könnte vor allem sinnvoll sein. für Modul- oder Klassen-Docstrings, da Sie auch auf diese Weise zeigen können, wie Sie es verwenden und gleichzeitig testen können.

Quelle

2009-03-02 11:25:15 MrTopf

+1: Verwende die RST Notation mit epydoc oder sphinx. –

Verwenden Sie "Doctests" ist ein guter Rat. Sinnvolle Beispiele können nicht nur zeigen, wie Edge Cases für den Benutzer behandelt werden, sondern Sie auch warnen, wenn Änderungen an Ihrem Code das erwartete Verhalten ändern. Sie können diese Beispiele auch jedes Mal erweitern, wenn Sie einen Fehler finden, der sicherstellt, dass er Sie nicht erneut anspricht oder Sie zumindest vor der Existenz dieses Fehlers warnen, solange er nicht korrigiert wird. – berna1111

Was es gehen sollte:

Alles, was Sie nicht von der Methode Unterschrift berichten. In diesem Fall ist das einzige nützliche Bit: displayName - wenn leer wird auf Feldname gesetzt.

Quelle

2009-03-02 10:44:16 eglasius

+1 für "alles, was Sie nicht von der Signatur der Methode sagen können" –

Spezifische Informationen, die dorthin gehen sollten, ist in den epydoc und sphinx-Projekten. siehe http://epydoc.sourceforge.net/epydoc.html –

Ich benutze gerne die Dokumentation, um so detailliert wie möglich zu beschreiben, was die Funktion macht, insbesondere das Verhalten in Eckfällen (a.k.a. edge cases). Idealerweise sollte ein Programmierer, der die Funktion verwendet, niemals den Quellcode betrachten müssen - in der Praxis bedeutet dies, dass, wann auch immer ein anderer Programmierer Quellcode betrachten muss, um Details der Funktionsweise der Funktion herauszufinden, dieses Detail wahrscheinlich hätte sein sollen in der Dokumentation erwähnt. Wie Freddy sagte, sollte alles, was der Signatur der Methode keine Details hinzufügt, wahrscheinlich nicht in einer Dokumentationszeichenfolge enthalten sein.

Quelle

2009-03-02 11:06:44

Die auffälligsten Dinge, die ich in einem Docstring einschließen kann, sind die Dinge, die nicht offensichtlich sind. Normalerweise beinhaltet dies Typinformationen oder Fähigkeitsanforderungen - z. "Erfordert ein dateiähnliches Objekt". In einigen Fällen wird dies aus der Unterschrift ersichtlich sein, in anderen Fällen nicht.

Eine weitere nützliche Sache, die Sie in Ihre Docstrings einfügen können, ist eine doctest.

Quelle

2009-03-02 12:34:34 sykora

Von PEP 8:

Konventionen für eine gute Dokumentation Strings zu schreiben (auch bekannt als "Docstrings") werden in PEP 257 verewigt.

Schreiben Sie Docstrings für alle öffentlichen Module, Funktionen, Klassen und Methoden. Docstrings sind für nicht-öffentliche Methoden nicht erforderlich, aber Sie sollten einen Kommentar haben, der beschreibt, was die Methode tut . Dieser Kommentar sollte nach der Zeile "def" erscheinen.

PEP 257 beschreibt gute Docstring-Konventionen. Beachten Sie, dass das "" ", das einen mehrzeiligen Docstring beendet, auf einer Zeile sein sollte und vorzugsweise eine Leerzeile vorangestellt ist.

Für einzeiler Docstrings, dann ist es in Ordnung, das Schließen ""“auf der gleichen Linie zu halten.

Quelle

2009-03-02 12:51:32 Xolve

Dies scheint die Syntax, aber nicht die Semantik zu umfassen. Vielleicht gibt es einen bevorzugten Stil, den Leute mögen? Versuchen Sie, alle @foobr-Schlüsselwörter in Docstrings zu füllen? – Konrads

Xolve sollte wirklich einen Link zu PEP 257 gepostet haben: http://www.python.org/dev/peps/pep-0257/ –

Check out numpy der Docstrings für gute Beispiele (zB http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

Die Docstrings aufgeteilt in mehrere Abschnitte und wie folgt aussehen:

Compute the sum of the elements of a list. 

Parameters 
---------- 
foo: sequence of ints 
    The list of integers to sum up. 

Returns 
------- 
res: int 
    sum of elements of foo 

See also 
-------- 
cumsum: compute cumulative sum of elemenents

Quelle

2011-01-14 10:56:25 Martin

beim Starten der Funktion Hinzufügen von doc-String des Hinzufügens allgemeinen Zweck Funktion zu beschreiben ist, was es tut, wha t es würde zurückkehren, und eine Beschreibung über Parameter. Sie können bei Bedarf Implementierungsdetails hinzufügen. Auch Sie können Details über den Autor hinzufügen, der den Code für zukünftige Entwickler geschrieben hat.

Quelle

2017-02-24 17:05:20

Antwort

Verwandte Themen