Gibt es eine allgemein akzeptierte Möglichkeit, Funktionen in Python zu kommentieren? Ist folgendes akzeptabel?
#########################################################
# Create a new user
#########################################################
def add(self):Antworten:
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:
- 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.- 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:
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:
"""def)? (Keine rhetorische Frage.)
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
"""