von: Konstantin
aktualisiert: Sept. 19, 2024
In diesem Artikel zeige ich dir was du beim Kommentieren in Python beachten musst, damit du wirklich gute Kommentare schreibst!
Kurz zusammengefasst gibt es drei Möglichkeiten, Kommentare in deinen Code einzufügen:
#) verwenden: alles was nach dem # in der Zeile steht, wird ignoriert. """ oder ''') Kommentare über mehrere Zeilen verwenden.Du erstellst einen einzeiligen Kommentar, indem du das Rautezeichen # am Anfang der Zeile schreibst. Alternativ kannst du in eine Zeile ein Stück Code schreiben und anschließend das Rautezeichen verwenden, um diesen Code zu kommentieren. Alles, was nach dem # kommt, wird vom Python-Interpreter ignoriert. Du kannst nach dem Rautezeichen also alles Schreiben, ohne dass es Einfluss auf die Ausführung deines Codes hat.
# Ich bin ein einzeiliger Kommentar!
print("Hallo, Welt!") # Ich bin auch ein Kommentar. Der Befehl print("Hallo, Welt!" wird ausgeführt.Natürlich kannst du mehrzeilige Kommentare einfach erstellen indem du vor jede Zeile das Rautensymbol setzt. Das kann allerdings etwas mühsam und unübersichtlich werden.
# Das ist ein mehrzeiliger Kommentar.
# Er erstreckt sich über mehrere Zeilen,
# aber jede Zeile beginnt mit einem `#`.Besser ist es wenn du stattdessen dreifache Anführungszeichen verwendest. Beide Varianten (''' oder """) funktionieren. Technisch gesehen handelt es sich hierbei nicht um einen Kommentar, denn Python kennt keine Syntax für mehrzeilige Kommentare. Eigentlich ist das ein String, der vom Interpreter schlicht ignoriert wird, so lange er nicht im eigentlichen Code verwendet wird (z.B. durch das Zuweisen zu einer Variablen).
'''
Das ist ebenfalls ein mehrzeiliger Kommentar.
Obwohl es sich eigentlich um einen String handelt,
wird er vom Interpreter ignoriert,
wenn er nicht verwendet wird.
'''Wenn du eine Funktion schreibst, ist es eine gute Praxis, diese direkt zu dokumentieren. Dafür gibt es in Python die sogenannte Docstring-Syntax. Ein Docstring ist ein spezieller String, der direkt unter der Definition einer Funktion, Methode oder Klasse steht und beschreibt, was diese Funktion tut. Du schreibst ihn in Triple-Quotes (''' oder """):
def addiere_zahlen(a, b):
"""
Diese Funktion addiert zwei Zahlen und gibt das Ergebnis zurück.
Parameter:
a: Die erste Zahl.
b: Die zweite Zahl.
Rückgabewert:
Die Summe von a und b.
"""
return a + bDer Vorteil eines Docstrings ist, dass er von Tools wie IDEs und automatisierten Dokumentationsgeneratoren ausgelesen werden kann. Außerdem bleibt er direkt mit der Funktion verknüpft, sodass du ihn leicht findest und ändern kannst.
Kommentare kannst du auch gut nutzen, um Code "auszukommentieren" und verschiedene Varianten zu testen. Auf diese Weise kannst du schauen, ob die eine oder andere Variante besser funktioniert. So kannst du deinen Code debuggen bzw. verbessern, ohne gleich den Code zu löschen.
In Beispiel unten wird die Zeile z = x + y auskommentiert, um zu testen, wie der Code ohne diese Berechnung funktioniert. Wenn du den Kommentar entfernst, wird diese Zeile wieder ausgeführt.
# Ursprünglicher Code:
x = 5
y = 10
# Debugging: Hier "deaktivierst" du die nächste Zeile:
# z = x + y
# Stattdessen gibst du nur x und y aus:
print(x)
print(y)
# Später kannst du die Zeile wieder aktivieren:
z = x + y
print(z)Analog dazu kannst du auch einen ganzen Bereich auskommentieren. Hierzu solltest du mehrzeilige Kommentare einsetzen. Dies funktioniert ähnlich wie bei einzeiligen Kommentaren. Schau dir das folgende Beispiel dazu an:
x = 10
y = 20
# Der folgende Block wurde "auskommentiert"
'''
if x > y:
print("x ist größer als y")
else:
print("y ist größer als x")
'''Achte darauf, dass du beim Auskommentieren mit dreifachen Anführungszeichen keine bereits vorhandenen Anführungszeichen (z.B. in Docstrings) übersiehst. Um das zu illustrieren, habe ich das Beispiel von oben hier nochmals aufgeführt. Diesmal habe ich die Strings in dreifache Anführungszeichen gepackt.
x = 10
y = 20
# Der folgende Block soll "auskommentiert" werden:
"""
if x > y:
print("""x ist größer als y""")
else:
print("""y ist größer als x""")
"""Der Code funktioniert allerdings nicht korrekt, da in diesem Fall die vorhanden dreifachen Anführungszeichen übersehen wurden und deshalb die beiden Strings x ist größer als y sowie y ist größer als x als Code gelesen werden.
Achte darauf, dass du beim Auskommentieren von mehreren Zeilen mit dreifachen Anführungszeichen """ keine bereits vorhandenen Anführungszeichen übersiehst. Ansonsten wird der falsche Code-Block auskommentiert und es kommt zu einem Fehler. Tip: Verwende immer Code-Editoren oder IDEs mit Syntax-Highlighting. Dann solltest du so etwas sofort sehen.
Kommentare gehören zu gut geschriebenen Code dazu! Und eigentlich ist es ja ganz einfach: du setzt eine Raute in die Zeile und beschreibst deinen Code. Aber Vorsicht: auch beim Kommentieren gilt die Regel "Weniger ist mehr". Beschränke dich daher auf nötige und sinnvolle Kommentare. Wie du das genau machst, lernst du in den nachfolgenden Abschnitten!
Manchmal führt der Eifer, alles zu kommentieren, dazu, dass der Code mit Kommentaren überfrachtet wird. Zu viele Kommentare können deinen Code schnell unübersichtlich machen und die Lesbarkeit verschlechtern. Kommentiere daher nur das, was wirklich nötig ist und halte deine Kommentare klar und präzise. Idealerweise schreibst du deinen Code direkt so, dass er aus sich heraus verständlich ist. Oft kannst du Kommentare einfach weglassen, insbesondere wenn sie völlig überflüssig sind. Schauen wir uns das Beispiel von weiter oben nochmal an:
def addiere_zahlen(a, b):
"""
Diese Funktion addiert zwei Zahlen und gibt das Ergebnis zurück.
Parameter:
a: Die erste Zahl.
b: Die zweite Zahl.
Rückgabewert:
Die Summe von a und b.
"""
return a + bHier ist der der längere Docstring in der Funktion völlig überflüssig. Der Name der Funktion sagt bereits aus, dass zwei Zahlen addiert werden. Wenn du dir den Code ansiehst, ist das ebenfalls offensichtlich. Das Beispiel zeigt auch, dass ein gut gewählter Funktionsname an sich bereits ein wichtiger "Kommentar" oder Beitrag zum Verständnis ist. Du kannst den Namen vielleicht noch etwas verbessern von addiere_zahlen(a, b) zu addiere_zwei_zahlen(a, b). Damit ist sehr klar was die Funktion macht. Gut gewählte "sprechende" Namen für Funktionen oder Variablen ersetzen oft überflüssige Kommentare!
Gerade wenn du dabei bist, ein neues Programm oder Skript zu schreiben wirst du deinen Code regelmäßig optimieren und verbessern. Vergiss dabei nicht, deine Kommentare zu aktualisieren! Veraltete Kommentare können dich oder andere verwirren und dir im Zweifelsfall viel Zeit rauben, wenn du nach mehreren Monaten nicht mehr mit deinen Kommentaren zurechtkommst. Aktualisiere deine Kommentare also regelmäßig.
Wenn du an deinem neuen Programm arbeitest, wirst du immer mal wieder Code auskommentieren und dafür neuen Code ausprobieren. Oft ist die Versuchung groß den alten Code einfach im Skript zu lassen, denn man könnte ihn ja vielleicht doch mal wieder brauchen. Um es ganz klar zu sagen: Keine gute Idee! Das überfrachtet deine Skripte und du oder andere finden sich über kurz oder lang nicht mehr zurecht. Hier solltest du rigoros vorgehen und alten Code einfach streichen!
Wenn du dich von deinem alten Code nicht trennen willst, kannst du eventuell alte Versionen deines Codes separat speichern. Idealerweise fängst du frühzeitig an, dich mit Versionskontrolle und git zu beschäftigen. Git ist der Goldstandard, wenn es darum geht alte Versionen deines Codes zu speichern und zu verwalten sowie Änderungen intelligent zu dokumentieren. Vor allem wenn du dich dabei ertappst, größere Änderungen als Kommentare in deinem Code zu dokumentieren ist es Zeit für git und professionelle Versionskontrolle:
"""
Änderungen:
- 2024-03-01: Habe Funktion xy entfernt, da sie überflüssig wurde.
- 2024-04-17: Verschiedene Vereinfachungen.
- 2024-06-13: Mehrere Bugs entfernt.
- 2024-08-07: Neue Funktion hinzugefügt, die Berechnung xy durchführt.
"""Kommentare sind zum Beispiel notwendig, um bestimmte Hintergrundinformationen zu liefern oder das "Warum" zu erklären. Der Code sollte aus sich heraus das "Wie" erklären (s.o.). Es sollte also ersichtlich sein wie der Code funktioniert. Hintergrundinfos können z.B. bestimmte Geschäftslogiken sein oder es kann sinnvoll sein Sicherheitsmaßnahmen zu erläutern (z.B. Umgebungsvariablen oder Code der ausgelagert wurde). Bei besonders komplizierte Algorithmen kannst du auch mal einen erläuternden Kommentar hinzufügen.
Im Beispiel unten wird im Docstring erläutert, wie der Bremsweg berechnet wird.
def berechne_bremsweg(geschwindigkeit, gefahrenbremsung=False) -> float:
"""
Die Funktion berechnet den Bremsweg anhand einer gängigen Faustformel. Der tatsächliche
Bremsweg hängt insbesondere von Straßenbedingungen ab. (Hinweis: der Reaktionsweg muss noch zum Bremsweg
addiert werden, um den kompletten Anhalteweg zu errechnen. Hier nicht berücksichtigt.)
Bei einer Gefahrenbremsung wird davon ausgeganngen, dass sich der Bremsweg etwa halbiert.
Infos unter:
https://www.tuev-nord.de/de/privatkunden/ratgeber-und-tipps/sicherheit/anhalteweg-und-bremsweg-berechnen/
"""
bremsweg = (geschwindigkeit/10) * (geschwindigkeit/10)
if gefahrenbremsung:
bremsweg = bremsweg/2
return str(bremsweg) + " Meter"
print(berechne_bremsweg(100, True))
# Ausgabe: 50.0 MeterIn vielen IDEs kannst du einen Kommentar für eine Zeile schnell einfügen, indem du Strg + / (Windows/Linux) oder Cmd + / (Mac) drückst. Dies kommentiert die aktuelle Zeile oder hebt den Kommentar auf. Je nach Umgebung kann es auch leichte Abweichungen oder Ergänzungen geben:
Strg + /, um eine Zeile zu kommentieren. Für einen Block benutze Strg + Shift + /.Strg + / für einzelne Zeilen. Mehrzeilige Kommentare kannst du mit Alt + Shift + A einfügen.Strg + / verwenden, um eine Zelle oder eine Zeile zu kommentieren.Gut platzierte und durchdachte Kommentare können den Unterschied zwischen gutem und schlechtem Code ausmachen. Viel wichtiger ist aber, dass du versuchst den Code an sich schon sehr lesbar und verständlich zu schreiben. Je einfacher und klarer dein Code ist, desto weniger Kommentare benötigst du. Verwende eindeutige und beschreibende Namen für Variablen und Funktionen und setze Kommentare sinnvoll und sparsam ein. Falls du übrigens gerade erst damit beginnst, Python zu lernen, dann schau dir doch meinen Python Kurs mal an.