Python-Kommentare richtig erstellen

Kommentare sind Notizen, die Programmierer ihrem Code hinzufügen, um zu erklären, was dieser Code tun soll. Die Compiler oder Interpreter, die den Code in die Tat umsetzen, ignorieren Kommentare, aber sie können für die Verwaltung von Softwareprojekten unerlässlich sein.

Kommentare helfen dabei, anderen Programmierern Ihren Python-Code zu erklären, und können Sie daran erinnern, warum Sie Ihre Entscheidungen getroffen haben. Kommentare erleichtern das Debuggen und Überarbeiten von Code, indem sie zukünftigen Programmierern helfen, die Designentscheidungen hinter Software zu verstehen.

Obwohl Kommentare in erster Linie für Entwickler gedacht sind, kann das Schreiben effektiver Kommentare auch dazu beitragen, eine hervorragende Dokumentation für die Benutzer Ihres Codes zu erstellen. Mithilfe von Dokumentgeneratoren wie Sphinx für Python-Projekte können Kommentare in Ihrem Code Inhalte für Ihre Dokumentation liefern.

Schauen wir unter die Haube des Kommentierens in Python.

Kommentare in Python

Gemäß dem Python PEP 8 Style Guide gibt es beim Schreiben von Kommentaren mehrere Dinge zu beachten:

• Kommentare sollten immer aus vollständigen und prägnanten Sätzen bestehen.
• Es ist besser, gar keinen Kommentar zu haben als einen, der schwer verständlich oder ungenau ist.
• Kommentare sollten regelmäßig aktualisiert werden, um Änderungen in Ihrem Code widerzuspiegeln.
• Zu viele Kommentare können ablenken und die Codequalität mindern. Kommentare sind nicht erforderlich, wenn der Zweck des Codes offensichtlich ist.

In Python wird eine Zeile als Kommentar deklariert, wenn sie mit dem # -Symbol beginnt. Wenn der Python-Interpreter in Ihrem Code auf # trifft, ignoriert er alles nach diesem Symbol und erzeugt keinen Fehler. Es gibt zwei Möglichkeiten, einzeilige Kommentare zu deklarieren: Inline-Kommentare und Blockkommentare.

Inline-Kommentare

Inline-Kommentare bieten kurze Beschreibungen von Variablen und einfachen Operationen und stehen in derselben Zeile wie die Code-Anweisung:

 border = x + 10 # Make offset of 10px

Der Kommentar erklärt die Funktion des Codes in derselben Anweisung wie der Code.

Kommentare blockieren

Blockkommentare werden verwendet, um komplexe Logik im Code zu beschreiben. Blockkommentare in Python sind ähnlich aufgebaut wie Inline-Kommentare – der einzige Unterschied besteht darin, dass Blockkommentare in eine separate Zeile geschrieben werden:

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

Beachten Sie, dass bei der Verwendung von Blockkommentaren die Kommentare über dem Code stehen, den sie erklären. Der Python PEP8 Style Guide schreibt vor, dass eine Codezeile nicht mehr als neunundsiebzig Zeichen enthalten sollte, und Inline-Kommentare verschieben häufig Zeilen über diese Länge. Aus diesem Grund werden Blockkommentare geschrieben, um den Code in separaten Zeilen zu beschreiben.

Mehrzeilige Kommentare

Python unterstützt von Haus aus keine mehrzeiligen Kommentare, was bedeutet, dass es keine spezielle Vorkehrung für deren Definition gibt. Trotzdem werden oft mehrzeilige Kommentare verwendet.

Sie können aus mehreren einzeiligen Kommentaren einen mehrzeiligen Kommentar erstellen, indem Sie jeder Zeile ein # voranstellen:

 # interpreter # ignores # these lines

Sie können auch mehrzeilige Zeichenfolgensyntax verwenden. In Python können Sie mehrzeilige Zeichenfolgen definieren, indem Sie sie in """ , dreifache doppelte Anführungszeichen oder ''' , dreifache einfache Anführungszeichen setzen:

 print("Multi-Line Comment") """ This String is Multi line """

Im obigen Code wird die mehrzeilige Zeichenfolge keiner Variablen zugewiesen, wodurch die Zeichenfolge wie ein Kommentar funktioniert. Zur Laufzeit ignoriert Python den String und wird nicht in den Bytecode aufgenommen. Das Ausführen des obigen Codes erzeugt die folgende Ausgabe:

 Multi-Line Comment

Besondere Kommentare

Kommentare dienen nicht nur dazu, Ihren Code lesbar zu machen, sondern dienen auch einigen speziellen Zwecken in Python, z. B. der Planung zukünftiger Code-Ergänzungen und der Erstellung von Dokumentationen.

Python-Docstring-Kommentare

In Python sind Docstrings mehrzeilige Kommentare, die erklären, wie eine bestimmte Funktion oder Klasse verwendet wird. Die Dokumentation Ihres Codes wird durch die Erstellung hochwertiger Docstrings verbessert. Während Sie mit einer Funktion oder Klasse arbeiten und die eingebaute Funktion help(obj) verwenden, können Docstrings hilfreich sein, um einen Überblick über das Objekt zu geben.

Python PEP 257 bietet eine Standardmethode zum Deklarieren von Docstrings in Python, wie unten gezeigt:

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

Im obigen Code stellte der Dokumentstring Details zur Funktionsweise der zugehörigen Funktion bereit. Mit Dokumentationsgeneratoren wie Sphinx kann dieser Docstring verwendet werden, um Benutzern Ihres Projekts einen Überblick über die Verwendung dieser Methode zu geben.

Ein direkt unterhalb der Funktions- oder Klassensignatur definierter Dokumentstring kann auch mithilfe der integrierten help() Funktion zurückgegeben werden. Die help() Funktion nimmt einen Objekt- oder Funktionsnamen als Argument und gibt die Docstrings der Funktion als Ausgabe zurück. Im obigen Beispiel kann help(get_person) aufgerufen werden, um mit der get_person Funktion verknüpfte Dokumentzeichenfolgen anzuzeigen. Wenn Sie den obigen Code in einer interaktiven Shell mit dem Flag -i ausführen, können Sie sehen, wie dieser Docstring von Python geparst wird. Führen Sie den obigen Code aus, indem python -i file.py .

Der Funktionsaufruf help(get_person) gibt einen Docstring für Ihre Funktion zurück. Die Ausgabe enthält get_person(name, age, d=False) , eine Funktionssignatur, die Python automatisch hinzufügt.

Das get_person.__ doc__ kann auch verwendet werden, um docstrings programmgesteuert abzurufen und zu ändern. Nach dem Hinzufügen von „Some more new information“ im obigen Beispiel erscheint es im zweiten Aufruf von help(get_person) . Dennoch ist es unwahrscheinlich, dass Sie Docstrings zur Laufzeit so dynamisch ändern müssen.

TODO-Kommentare

Beim Schreiben von Code kann es vorkommen, dass Sie bestimmte Zeilen oder ganze Blöcke zur Verbesserung hervorheben möchten. Diese Aufgaben werden durch TODO-Kommentare gekennzeichnet. TODO-Kommentare sind praktisch, wenn Sie Aktualisierungen oder Änderungen an Ihrem Code planen oder wenn Sie die Benutzer oder Mitarbeiter des Projekts darüber informieren möchten, dass bestimmte Abschnitte des Codes der Datei noch geschrieben werden müssen.

TODO-Kommentare sollten nicht als Pseudocode geschrieben werden – sie müssen nur kurz die Funktion des noch ungeschriebenen Codes erklären.

TODO-Kommentare und einzeilige Blockkommentare sind sich sehr ähnlich, und der einzige Unterschied zwischen ihnen besteht darin, dass TODO-Kommentare mit einem TODO-Präfix beginnen müssen:

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

Es ist wichtig zu beachten, dass, obwohl viele IDEs diese Kommentare für den Programmierer hervorheben können, der Python-Interpreter TODO-Kommentare nicht anders als Blockkommentare betrachtet.

Best Practices beim Schreiben von Python-Kommentaren

Es gibt eine Reihe von Best Practices, die beim Schreiben von Kommentaren befolgt werden sollten, um Zuverlässigkeit und Qualität zu gewährleisten. Im Folgenden finden Sie einige Tipps zum Schreiben hochwertiger Kommentare in Python.

Vermeiden Sie das Offensichtliche

Kommentare, die das Offensichtliche aussagen, fügen Ihrem Code keinen Wert hinzu und sollten vermieden werden. Zum Beispiel:

 x = x + 4 # increase x by 4

Dieser Kommentar ist nicht nützlich, da er einfach angibt, was der Code tut, ohne zu erklären, warum er getan werden muss. Kommentare sollten eher das „Warum“ als das „Was“ des Codes erklären, den sie beschreiben.

Nützlicher umgeschrieben könnte das obige Beispiel so aussehen:

 x = x + 4 # increase the border width

Halten Sie Python-Kommentare kurz und bündig

Halten Sie Ihre Kommentare kurz und leicht verständlich. Sie sollten in Standardschrift und nicht in Pseudocode geschrieben sein und die Notwendigkeit ersetzen, den eigentlichen Code zu lesen, um einen allgemeinen Überblick darüber zu bekommen, was er tut. Zu viele Details oder komplexe Kommentare machen die Arbeit eines Programmierers nicht einfacher. Zum Beispiel:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Der obige Kommentar enthält mehr Informationen, als für den Leser notwendig sind. Anstatt die Kernlogik anzugeben, sollten Kommentare eine allgemeine Zusammenfassung des Codes liefern. Dieser Kommentar kann wie folgt umgeschrieben werden:

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

Verwenden Sie Identifikatoren sorgfältig

Bezeichner sollten in Kommentaren sorgfältig verwendet werden. Das Ändern von Bezeichnernamen oder Fällen kann den Leser verwirren. Beispiel:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

Der obige Kommentar erwähnt class und argument , von denen keines im Code zu finden ist. Dieser Kommentar kann wie folgt umgeschrieben werden:

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

TROCKEN und NASS

Wenn Sie Code schreiben, sollten Sie sich an das DRY-Prinzip (Don't Repeat Yourself) halten und WET (alles zweimal schreiben) vermeiden.

Dies gilt auch für Kommentare. Vermeiden Sie die Verwendung mehrerer Anweisungen zur Beschreibung Ihres Codes, und versuchen Sie, Kommentare, die denselben Code erklären, in einem einzigen Kommentar zusammenzuführen. Es ist jedoch wichtig, beim Zusammenführen von Kommentaren vorsichtig zu sein: Das unvorsichtige Zusammenführen mehrerer Kommentare kann zu einem riesigen Kommentar führen, der gegen die Stilrichtlinien verstößt und für den Leser schwer zu verstehen ist.

Denken Sie daran, dass Kommentare die Lesezeit des Codes verkürzen sollten.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

Im obigen Code sind die Kommentare unnötig fragmentiert und können zu einem einzigen Kommentar zusammengeführt werden:

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

Konsistente Einrückung

Stellen Sie sicher, dass Kommentare auf derselben Ebene eingerückt sind wie der Code, den sie beschreiben. Wenn sie es nicht sind, kann es schwierig sein, ihnen zu folgen.

Dieser Kommentar ist beispielsweise nicht eingerückt oder richtig positioniert:

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

Es kann wie folgt umgeschrieben werden:

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

Zusammenfassung

Kommentare sind eine wichtige Komponente beim Schreiben von verständlichem Code. Die Investition, die Sie beim Schreiben eines Kommentars tätigen, wird Ihr zukünftiges Ich – oder andere Entwickler, die an Ihrer Codebasis arbeiten müssen – zu schätzen wissen. Durch das Kommentieren können Sie auch tiefere Einblicke in Ihren Code gewinnen.

In diesem Lernprogramm haben Sie mehr über Kommentare in Python erfahren, einschließlich der verschiedenen Arten von Python-Kommentaren, wann Sie sie verwenden und welche Best Practices Sie beim Erstellen befolgen sollten.

Das Schreiben guter Kommentare ist eine Fähigkeit, die erlernt und entwickelt werden muss. Um das Schreiben von Kommentaren zu üben, sollten Sie in Erwägung ziehen, zu einigen Ihrer früheren Projekte zurückzugehen und Kommentare hinzuzufügen. Um sich inspirieren zu lassen und Best Practices in Aktion zu sehen, sehen Sie sich gut dokumentierte Python-Projekte auf GitHub an.

Wenn Sie bereit sind, Ihre eigenen Python-Projekte live zu schalten, kann Kinstas Anwendungs-Hosting-Plattform Ihren Code in Sekundenschnelle von GitHub in die Cloud übertragen.