Kommentare
„Wenn die Implementierung schwer zu erklären ist, ist sie eine schlechte Idee.“
– Das Zen von Python
Man sollte Kommentare verwenden, um den Code so zu dokumentieren, warum er geschrieben wurde, so dass jeder ihn auch noch später verstehen kann. Hier sind einige wichtige Punkte, die man beim Hinzufügen von Kommentaren beachten sollte:
- Die Zeilenlänge von Kommentaren und Docstrings ist auf 72 Zeichen zu begrenzen.
- Es sind vollständige Sätze, die mit einem Großbuchstaben beginnen, zu verwenden.
- Wenn man den Code ändert, ist darauf zu achten, Kommentare zu aktualisieren.
Block-Kommentare
Man sollte Blockkommentare verwenden, um einen kleinen Abschnitt des Codes zu dokumentieren. Sie sind nützlich, wenn man mehrere Codezeilen schreiben muss, um eine einzige Aktion auszuführen, wie z. B. das Importieren von Daten aus einer Datei oder das Aktualisieren eines Datenbankeintrags. Sie sind wichtig, da sie anderen helfen, den Zweck und die Funktionalität eines bestimmten Codeblocks zu verstehen.
PEP 8 enthält die folgenden Regeln für das Schreiben von Blockkommentaren:
- Blockkommentare sollten auf der gleichen Ebene eingerückt werden wie der Code, den sie beschreiben.
- Man beginnt jede Zeile mit einem #, gefolgt von einem einfachen Leerzeichen.
- Man trennt Absätze durch eine Zeile, die ein einzelnes # enthält.
Hier ist ein Blockkommentar, der die Funktion einer for-Schleife erklärt. Es ist zu beachten, dass der Satz in eine neue Zeile umbricht, um die Zeilenbegrenzung von 79 Zeichen einzuhalten:
for i in range(0, 10): # Loop over i ten times and print out the value of i, followed by a # new line character print(i, '\n')
Wenn der Code sehr technisch ist, kann es manchmal notwendig sein, mehr als einen Absatz in einem Blockkommentar zu verwenden:
def quadratic(a, b, c, x): # Calculate the solution to a quadratic equation using the quadratic # formula. # # There are always two solutions to a quadratic equation, x_1 and x_2. x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a) x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a) return x_1, x_2
Wenn man nicht sicher sind, welcher Kommentartyp geeignet ist, sind Blockkommentare oft der richtige Weg. Man verwendet sie so oft wie möglich im Code, aber man sollte darauf achten, sie zu aktualisieren, wenn man Änderungen am Code vorgenommen hat!
Inline-Kommentare
Inline-Kommentare erläutern eine einzelne Anweisung in einem Codestück. Sie sind nützlich, um daran zu erinnern oder um anderen zu erklären, warum eine bestimmte Codezeile notwendig ist. Hier ist, was PEP 8 über sie zu sagen hat:
- Man verwendet Inline-Kommentare sparsam.
- Man schreibt Inline-Kommentare in dieselbe Zeile wie die Anweisung, auf die sie sich beziehen.
- Man trennt Inline-Kommentare durch zwei oder mehr Leerzeichen von der Anweisung.
- Man beginnt Inline-Kommentare mit einem # und einem einzelnen Leerzeichen, wie Blockkommentare.
- Man verwendet sie nicht, um das Offensichtliche zu erklären.
Manchmal können Inline-Kommentare notwendig erscheinen, aber man sollte prüfen, ob man stattdessen bessere Namenskonventionen verwenden kann.
Hier ist ein Beispiel:
x = 'John Smith' # Student Name
Der Inline-Kommentar liefert zusätzliche Informationen. Die Verwendung von x als Variablenname für den Namen einer Person ist jedoch eine schlechte Praxis. Der Inline-Kommentar ist überflüssig, wenn man die Variable umbenennt:
student_name = 'John Smith'
Inline-Kommentare, die das Offensichtliche erklären und den Code unübersichtlich machen, sind eine schlechte Praxis:
empty_list = [] # Initialize empty list x = 5 x = x * 5 # Multiply x by 5
Inline-Kommentare sind spezifischer als Blockkommentare, und es ist leicht, sie hinzuzufügen, wenn sie nicht notwendig sind, was zu Unordnung führt. Wenn man also nicht sicher ist, dass man einen Inline-Kommentar benötigt, ist der Code wahrscheinlich eher PEP 8-konform, wenn man sich an Blockkommentare hält.
Dokumentationsstrings („Documentation Strings“)
Dokumentationsstrings oder docstrings sind in doppelte („““) oder einfache (“‘) Anführungszeichen eingeschlossene Strings, die in der ersten Zeile einer Funktion, Klasse, Methode oder eines Moduls erscheinen. Man kann sie verwenden, um einen bestimmten Codeblock zu erklären und zu dokumentieren. Es gibt ein ganzes PEP, PEP 257, das Docstrings behandelt, deshalb enthält dieser Abschnitt hier nur eine kurze Zusammenfassung.
Die wichtigsten Regeln, die für docstrings gelten, sind die folgenden:
- Man umgibt docstrings mit drei doppelten Anführungszeichen auf beiden Seiten, wie in „““Dies ist ein docstring“““.
- Man schreibt sie für alle öffentlichen Module, Funktionen, Klassen und Methoden.
- Man setzt das „““, das einen mehrzeiligen docstring abschließt, in eine eigene Zeile:
def quadratic(a, b, c, x): """Löse eine quadratische Gleichung mit Hilfe der quadratischen Formel. Eine quadratische Gleichung hat die folgende Form: ax**2 + bx + c = 0 Es gibt immer zwei Lösungen für eine quadratische Gleichung: x_1 & x_2. """ x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a) x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a) return x_1, x_2
Bei einzeiligen docstrings sollte das abschliessende „““ in der gleichen Zeile stehen:
def quadratic(a, b, c, x): """Verwende die quadratische Formel""" x_1 = (- b+(b**2-4*a*c)**(1/2)) / (2*a) x_2 = (- b-(b**2-4*a*c)**(1/2)) / (2*a) return x_1, x_2