Was ist der richtige Weg, um Funktionen in Python zu kommentieren?

Gibt es eine allgemein akzeptierte Möglichkeit, Funktionen in Python zu kommentieren? Ist folgendes akzeptabel?

#########################################################
# Create a new user
#########################################################
def add(self):

Der richtige Weg, dies zu tun, besteht darin, eine Dokumentzeichenfolge bereitzustellen. Auf diese Weise help(add)wird auch Ihr Kommentar ausgespuckt.

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

Das sind drei doppelte Anführungszeichen, um den Kommentar zu öffnen, und drei weitere doppelte Anführungszeichen, um ihn zu beenden. Sie können auch eine beliebige gültige Python-Zeichenfolge verwenden. Es muss nicht mehrzeilig sein und doppelte Anführungszeichen können durch einfache Anführungszeichen ersetzt werden.

Siehe: PEP 257

Verwenden Sie eine Dokumentzeichenfolge, wie andere bereits geschrieben haben.

Sie können sogar noch einen Schritt weiter gehen und Ihrem Docstring einen Doctest hinzufügen, sodass das automatisierte Testen Ihrer Funktionen zum Kinderspiel wird.

Verwenden Sie eine Dokumentzeichenfolge :

Ein Zeichenfolgenliteral, das als erste Anweisung in einer Modul-, Funktions-, Klassen- oder Methodendefinition vorkommt. Eine solche Dokumentzeichenfolge wird zum __doc__besonderen Attribut dieses Objekts.

Alle Module sollten normalerweise Docstrings haben, und alle Funktionen und Klassen, die von einem Modul exportiert werden, sollten auch Docstrings haben. Öffentliche Methoden (einschließlich des __init__Konstruktors) sollten ebenfalls Dokumentzeichenfolgen enthalten. Ein Paket kann in der Modul-Dokumentzeichenfolge der __init__.pyDatei im Paketverzeichnis dokumentiert sein .

String-Literale, die an anderer Stelle im Python-Code vorkommen, können auch als Dokumentation dienen. Sie werden vom Python-Bytecode-Compiler nicht erkannt und sind nicht als Laufzeitobjektattribute zugänglich (dh nicht zugewiesen __doc__). Zwei Arten von zusätzlichen Dokumentzeichenfolgen können jedoch von Softwaretools extrahiert werden:

1. Zeichenfolgenliterale, die unmittelbar nach einer einfachen Zuweisung auf der obersten Ebene eines Moduls, einer Klasse oder einer __init__Methode auftreten, werden als "Attribut-Dokumentzeichenfolgen" bezeichnet.
2. Zeichenfolgenliterale, die unmittelbar nach einer anderen Dokumentzeichenfolge auftreten, werden als "zusätzliche Dokumentzeichenfolgen" bezeichnet.

In PEP 258 , "Docutils Design Specification" [2] , finden Sie eine detaillierte Beschreibung der Attribute und zusätzlicher Dokumentzeichenfolgen ...

Die Prinzipien des guten Kommentierens sind ziemlich subjektiv, aber hier sind einige Richtlinien:

• Funktionskommentare sollten die Absicht einer Funktion beschreiben, nicht die Implementierung
• Skizzieren Sie alle Annahmen, die Ihre Funktion in Bezug auf den Systemstatus macht. Wenn globale Variablen (tsk, tsk) verwendet werden, listen Sie diese auf.
• Achten Sie auf übermäßige ASCII-Grafik . Lange Hashes scheinen die Kommentare leichter lesbar zu machen, aber es kann ärgerlich sein, mit ihnen umzugehen, wenn sich Kommentare ändern
• Nutzen Sie Sprachfunktionen, die eine automatische Dokumentation bieten, z. B. Dokumentzeichenfolgen in Python, POD in Perl und Javadoc in Java

Lesen Sie mehr über die Verwendung von Docstrings in Ihrem Python-Code.

Gemäß den Python- Docstring-Konventionen :

Die Dokumentzeichenfolge für eine Funktion oder Methode sollte ihr Verhalten zusammenfassen und ihre Argumente, Rückgabewerte, Nebenwirkungen, ausgelösten Ausnahmen und Einschränkungen hinsichtlich des Aufrufs dokumentieren (alle, falls zutreffend). Optionale Argumente sollten angegeben werden. Es sollte dokumentiert werden, ob Schlüsselwortargumente Teil der Schnittstelle sind.

Es wird keine goldene Regel geben, sondern Kommentare abgeben, die den anderen Entwicklern in Ihrem Team (falls Sie eine haben) oder sogar sich selbst etwas bedeuten, wenn Sie sechs Monate später darauf zurückkommen.

Ich würde mich für eine Dokumentationspraxis entscheiden, die in ein Dokumentationswerkzeug wie Sphinx integriert ist .

Der erste Schritt ist die Verwendung von docstring:

def add(self):
 """ Method which adds stuff
 """

Ich würde noch einen Schritt weiter gehen, als nur "benutze einen Docstring" zu sagen. Wählen Sie ein Dokumentationsgenerierungswerkzeug wie pydoc oder epydoc (ich verwende epydoc beim Pyparsing) und verwenden Sie die von diesem Werkzeug erkannte Markup-Syntax. Führen Sie dieses Tool während der Entwicklung häufig aus, um Lücken in Ihrer Dokumentation zu identifizieren. In der Tat können Sie sogar davon profitieren, die Dokumentzeichenfolgen für die Mitglieder einer Klasse zu schreiben, bevor Sie die Klasse implementieren.

Verwenden Sie Dokumentzeichenfolgen .

Dies ist die in PyCharm integrierte Konvention für Funktionsbeschreibungskommentare:

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

Obwohl ich damit einverstanden bin, dass dies kein Kommentar sein sollte, sondern ein Dokumentstring, wie die meisten (alle?) Antworten vermuten lassen, möchte ich numpydoc (einen Docstring-Styleguide) hinzufügen .

Wenn Sie dies so tun, können Sie (1) automatisch Dokumentation erstellen und (2) Personen erkennen dies und haben es leichter, Ihren Code zu lesen.

Sie können dazu drei Anführungszeichen verwenden.

Sie können einfache Anführungszeichen verwenden:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

Oder doppelte Anführungszeichen:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """