Wie sinnvoll Docstrings schreiben?

StackOverflow https://stackoverflow.com/questions/601900

  •  03-07-2019
  •  | 
  •  

Frage

Was ist Ihrer Meinung nach ist ein sinnvoller docstring? Was erwarten Sie dort beschrieben werden?

Zum Beispiel, betrachten Sie dieses __init__ der Python-Klasse: 

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
    """

Haben Sie diese sinnvoll finden? Stellen Sie Ihre guten / schlechten Beispiele für alle kennen (und eine allgemeine Antwort, damit es akzeptiert werden kann).

War es hilfreich?

Lösung

ich mit „Alles, was man nicht von der Methode Unterschrift sagen kann“ zustimmen. Es könnte auch bedeuten, zu erklären, was eine Methode / Funktion zurückkehrt.

Sie können auch Sphinx (und reStructuredText Syntax) zu Dokumentationszwecken in Ihrem Docstrings verwenden möchten. So können Sie leicht diese in Ihrer Dokumentation enthalten. Für ein Beispiel Besuche z.B. repoze.bfg die diese nutzt extensiv ( Beispieldatei , Dokumentation Beispiel ).

Eine andere Sache, ein in Docstrings setzen kann, ist auch Doctests . Dies könnte Sinn machen esp. für Modul oder Klasse Docstrings wie können Sie auch, dass die Art und Weise zeigen, wie es zu benutzen und hat diese prüfbar zugleich.

Andere Tipps

PEP 8 :

  

Konventionen für das Schreiben von guter Dokumentation Strings (auch bekannt als   "Docstrings") sind unsterblich in PEP 257 .

     
      
  • Schreiben Docstrings für alle öffentlichen Module, Funktionen, Klassen und Methoden. Docstrings sind nicht für nicht-öffentliche Methoden notwendig, aber Sie   sollte einen Kommentar haben, dass das Verfahren funktioniert beschreibt. Diese   Kommentar soll nach der „def“ Zeile angezeigt.
    •   
  • PEP 257 gute docstring Konventionen beschreibt. Beachten Sie, dass vor allem die „““dass endet ein mehrzeiliges docstring auf eine sein sollte,   Linie von selbst, und vorzugsweise durch eine Leerzeile vorangestellt.
    •   
  • Für einzeiler Docstrings, es ist okay, das Schließen „““auf der gleichen Linie zu halten.
    •   

Was sollte es gehen:

Alles, was man nicht von der Methode Unterschrift berichten. In diesem Fall ist die einzige Bit nützlich ist: display - wenn leer Feldnamen gesetzt werden

.

Überprüfen Sie numpy des Docstrings für gute Beispiele (zB http: / /github.com/numpy/numpy/blob/master/numpy/core/numeric.py ).

Die Docstrings in mehrere Abschnitte aufgeteilt 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

Die auffälligsten Dinge, die ich mir vorstellen kann in einem docstring enthalten sind die Dinge, die nicht offensichtlich sind. Normalerweise enthalten diese Informationen eingeben oder Fähigkeitsanforderungen - zB. „Erfordert ein dateiähnliche Objekt“. In einigen Fällen wird dies aus der Signatur ersichtlich sein, nicht so in anderen Fällen.

Eine andere nützliche Sache, die Sie sich in Ihrem Docstrings setzen kann, ist ein doctest.

Ich mag die Dokumentation verwenden, so detailliert wie möglich zu beschreiben, was die Funktion macht, vor allem das Verhalten an der Ecke Fällen (auch bekannt als Grenzfall). Idealerweise sollte ein Programmierer die Funktion nie auf dem Quellcode suchen - in der Praxis bedeutet das, dass immer dann, wenn ein anderer Programmierer an Quellcode aussehen muss einiges Detail herauszufinden, wie die Funktion arbeitet, soll dieses Detail wohl gewesen sein in der Dokumentation erwähnt. Als Freddy sagte, alles, was nicht jedes Detail auf die Methode der Unterschrift fügt wahrscheinlich nicht in einer Dokumentation String sein.

Im allgemeinen Zweck Hinzufügen doc Zeichenfolge der Zugabe in Start der Funktion zu beschreiben, ist Funktion, was es tut, was es zurückkehren würde, und eine Beschreibung über Parameter. Sie können Implementierungsdetails hinzufügen, falls erforderlich. Auch können Sie Details über den Autor hinzu, die den Code für zukünftige Entwickler geschrieben.

Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top