Python-Kommentare: einzeilig, mehrzeilig und Docstrings

Kommentare sind für Menschen

Python ignoriert Kommentare. Das ist der ganze Trick. Alles, was du als Kommentar markierst, ist für den Interpreter unsichtbar — es ist rein für die Person da, die deinen Code liest, meistens dein zukünftiges Ich in sechs Monaten, das sich fragt, was dein vergangenes Ich sich dabei gedacht hat.

Trotzdem: Ein Kommentar, der nur wiederholt, was der Code offensichtlich tut, lohnt sich nicht. Die besten Kommentare erklären das Warum — eine Einschränkung, einen Workaround, eine Entscheidung, die aus dem Code selbst nicht hervorgeht. Das Was sagt dir der Code schon.

Einzeilige Kommentare mit #

Die Grundform ist ein # gefolgt von deiner Notiz:

Du kannst einen kurzen Kommentar auch ans Ende einer Zeile hängen. Konvention: mindestens zwei Leerzeichen vor dem #:

Python liest ein # überall außerhalb eines Strings und behandelt den Rest der Zeile als Kommentar. Das „außerhalb eines Strings“ ist wichtig: # innerhalb von Anführungszeichen ist einfach ein Zeichen.

Das #section-2 im String ist Teil der URL. Python schaltet erst nach dem Schließen des Strings in den „Kommentar“-Modus.

Mehrere Zeilen auskommentieren

Python hat keinen /* */-Blockkommentar. Um mehrere Zeilen zu überspringen, setz # an den Anfang jeder:

Diese #-Zeichen tippst du so gut wie nie von Hand. Jeder vernünftige Editor hat einen Shortcut „Zeilenkommentar umschalten“, der bei jeder ausgewählten Zeile # hinzufügt oder entfernt:

• VS Code: Cmd + / (macOS) oder Strg + / (Windows/Linux)
• PyCharm: Cmd + / oder Strg + /
• Vim: hängt von deinen Plugins ab; vim-commentary belegt gcc für eine einzelne Zeile und gc für eine Auswahl.

Lerne den Shortcut deines Editors einmal, und „diesen Block auskommentieren, um was zu testen“ wird zur Ein-Tasten-Operation.

Der Trick mit dreifach zitierten Strings (und warum es kein echter Kommentar ist)

Manchmal siehst du Code wie diesen:

Technisch ist das ein String-Ausdruck, der verworfen wird. Python liest ihn, wertet ihn aus und wirft das Ergebnis weg. Er verhält sich wie ein Kommentar, ist aber keiner. Stilistisch ist das nur an einer bestimmten Stelle eine gute Idee: als Docstring.

Docstrings: der einzige Ort, an den dreifache Anführungszeichen gehören

Ein Docstring ist ein dreifach zitierter String, der als allererste Anweisung in einer Funktion, Klasse oder einem Modul steht. Python erkennt ihn als Dokumentation und stellt ihn zur Laufzeit über die Funktion help() und das Attribut __doc__ bereit:

Zwei Dinge machen Docstrings angenehm:

1. Werkzeuge wie IDEs, help() und Dokumentationsgeneratoren lesen sie automatisch aus. Ein Kommentar über der Funktion bekommt davon nichts ab.
2. Sie beschreiben die Funktion an der Aufrufstelle — wenn jemand im Editor über discount(...) hovert, erscheint der Docstring als Tooltip.

Es gibt eine Konvention (PEP 257) für den Inhalt eines Docstrings: eine Einzeilen-Zusammenfassung in der ersten Zeile, eine Leerzeile, dann bei Bedarf eine längere Beschreibung. Stress dich am ersten Tag nicht mit dem exakten Format — ein schlichter Einzeiler ist immer noch viel besser als gar kein Docstring.

Was gute Kommentare tatsächlich sagen

Ein paar Leitlinien, die dir später viel Ärger ersparen:

• Beschreibe das Warum, nicht das Was. # Loop over the users ist Rauschen; # Retry on 503 — Redis sometimes dies mid-deploy ist Gold.
• Aktualisiere Kommentare, wenn du den Code änderst. Ein falscher Kommentar ist schlimmer als keiner. Veraltete Kommentare führen zukünftige Leser aktiv in die Irre.
• Kommentier keinen Code aus und lass ihn liegen. Brauchst du ihn nicht, lösch ihn. Die Versionsverwaltung erinnert sich. Eine Datei, durchsetzt mit auskommentierten Blöcken, wird schnell unglaubwürdig.
• Lass das Offensichtliche weg. x = x + 1 # increment x trägt nichts bei.

Unterm Strich

Kommentare sind günstig zu schreiben und günstig wegzulassen. Greif zu ihnen, wenn du einen Hinweis hinterlässt, für den dir ein Leser dankt — ein subtiler Grund, warum etwas funktioniert, ein Link zu einem Issue, eine Warnung vor einem Randfall. Nutze Docstrings, wenn du eine Funktion oder Klasse definierst. Ansonsten lass klare Namen und kleine Funktionen die Arbeit übernehmen.

Du hast jetzt alles, was du brauchst, um eine Python-Datei zu lesen und zu schreiben. Im nächsten Kapitel fängt die Sprache tatsächlich an, Dinge zu tun: Variablen, Datentypen und die Werte, die Python halten kann.