Python-Kommentare — Einzeilig, Mehrzeilig & Best Practices

Kommentare sind Zeilen in deinem Quellcode, die der Python-Interpreter vollständig ignoriert. Sie existieren für menschliche Leser — um Absichten zu erklären, Entscheidungen zu dokumentieren und Probleme zu kennzeichnen — ohne das Laufzeitverhalten des Programms zu beeinflussen. Dieses Kapitel behandelt alle Arten von Python-Kommentaren, wann man welche verwendet und welche Konventionen große Codebasen lesbar halten.

Einzeilige Kommentare

Ein einzeiliger Kommentar beginnt mit einem Rautezeichen (#). Alles vom # bis zum Ende der Zeile wird vom Interpreter ignoriert.

# Calculate the area of a circle
radius = 5
area = 3.14159 * radius ** 2
print(area)  # outputs 78.53975

Der Kommentar in der letzten Zeile — nach ausführbarem Code in derselben Zeile platziert — wird als Inline-Kommentar bezeichnet. Verwende ihn sparsam; reserviere ihn für wirklich nicht offensichtliche Logik, anstatt zu wiederholen, was der Code bereits aussagt.

Wann einzeilige Kommentare einsetzen

• Erkläre warum eine Entscheidung getroffen wurde, nicht was der Code tut (das zeigt der Code selbst).
• Markiere temporäre Workarounds: # TODO: replace with database lookup.
• Deaktiviere eine einzelne Zeile vorübergehend beim Debuggen.

# FIXME: division by zero if user_count is 0
average = total_score / user_count

Mehrzeilige Kommentare

Python verfügt nicht über eine dedizierte Syntax für mehrzeilige Kommentare wie C mit /* ... */. Die idiomatische Methode, mehrere Zeilen zu überspannen, besteht darin, aufeinanderfolgende einzeilige Kommentare zu verwenden, die jeweils mit # beginnen.

# This function converts a temperature in Celsius to Fahrenheit.
# The formula is: F = (C * 9/5) + 32
# Returns a float rounded to two decimal places.
def celsius_to_fahrenheit(c):
    return round((c * 9 / 5) + 32, 2)

print(celsius_to_fahrenheit(100))  # 212.0
print(celsius_to_fahrenheit(0))    # 32.0

Die meisten Python-Editoren und IDEs ermöglichen es dir, mehrere Zeilen auszuwählen und # auf allen gleichzeitig umzuschalten (normalerweise Ctrl+/ oder Cmd+/).

Docstrings — strukturierte Dokumentationskommentare

Python hat eine spezielle String-Literal-Konvention namens Docstring (kurz für Dokumentations-String). Ein Docstring ist ein dreifach angeführter String, der unmittelbar nach einem def-, class- oder module-Header platziert wird. Obwohl es technisch gesehen ein String-Ausdruck und kein Kommentar ist, dient er als Standard-Dokumentationsmechanismus und ist zur Laufzeit über das __doc__-Attribut zugänglich.

def greet(name):
    """Return a personalised greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting string.
    """
    return f"Hello, {name}!"

print(greet("Alice"))        # Hello, Alice!
print(greet.__doc__)         # prints the docstring above

Dreifach angeführte Strings als Block-Kommentare

Da Python String-Literale verwirft, die nichts zugewiesen sind, wird ein dreifach angeführter String für sich allein (nicht in einer def/class-Position) manchmal als informeller Block-Kommentar verwendet:

"""
This script processes the daily sales report.
It reads from sales.csv, aggregates by region,
and writes a summary to report.txt.
"""

import csv

Dieses Muster funktioniert, hat aber einen subtilen Nachteil: Anders als #-Kommentare parst der Interpreter den String und kann ihn im kompilierten Bytecode behalten. Für Dokumentation auf Modulebene bevorzuge einen richtigen Modul-Docstring (die allererste Anweisung in der Datei). Für andere mehrzeilige Erklärungen innerhalb von Funktionen bleib bei aufeinanderfolgenden #-Zeilen.

Code beim Debuggen auskommentieren

Das vorübergehende Deaktivieren von Code mit Kommentaren ist eine gängige Debugging-Technik:

def calculate_discount(price, rate):
    # discount = price * rate        # old flat-rate formula
    discount = price * rate if rate < 1 else price * (rate / 100)
    return price - discount

print(calculate_discount(100, 0.2))   # 80.0
print(calculate_discount(100, 20))    # 80.0

Sobald du die Korrektur bestätigt hast, entferne die auskommentierten Zeilen, anstatt sie dauerhaft in der Codebasis zu belassen — veralteter auskommentierter Code verwirrt künftige Leser.

Spezielle Kommentar-Direktiven

Python und seine Werkzeuge erkennen einige Kommentarzeilen mit maschinenlesbarer Bedeutung:

Die Shebang-Zeile

Auf Unix-ähnlichen Systemen kann die erste Zeile eines Skripts den Interpreter angeben:

#!/usr/bin/env python3
# This line tells the OS to run the file with python3.

print("Hello from a standalone script!")

Diese Zeile ist für Python ein Kommentar (sie beginnt mit #), aber das Betriebssystem verwendet sie, wenn die Datei direkt ausgeführt wird (./script.py).

Kodierungsdeklaration

Wenn deine Quelldatei eine andere Zeichenkodierung als UTF-8 verwendet (der Standard seit Python 3), deklariere sie in der ersten oder zweiten Zeile:

# -*- coding: utf-8 -*-

Python 3 verwendet standardmäßig UTF-8, daher ist dies heute selten erforderlich, aber du kannst es in Legacy-Code begegnen.

Type-Checker-Direktiven

Type-Checker wie mypy berücksichtigen spezielle Inline-Kommentare:

x = []  # type: ignore
result = some_function()  # type: ignore[return-value]

Diese unterdrücken bestimmte Typfehler, ohne das Laufzeitverhalten zu ändern. Weitere Informationen dazu, wie Python Typen behandelt, findest du im Kapitel Python Variables.

Best Practices für Kommentare

Wenn du diese Konventionen befolgst, werden deine Kommentare wirklich nützlich:

PEP 8 — Pythons offizieller Stileitfaden — empfiehlt:

• Inline-Kommentare sollten durch mindestens zwei Leerzeichen von der Anweisung getrennt sein.
• Jeder Inline-Kommentar sollte mit # (Raute, dann ein Leerzeichen) beginnen.
• Block-Kommentare, die sich auf den darunter liegenden Code beziehen, sollten auf derselben Ebene eingerückt sein.

def apply_tax(price, tax_rate):
    # Tax rate is expressed as a decimal (e.g., 0.07 for 7 %).
    # Prices must be non-negative; validation happens upstream.
    tax = price * tax_rate
    return price + tax  # total including tax

Häufige Fehler vermeiden

1. TODO-Kommentare ohne Nachverfolgung lassen

# TODO: handle the case where the file does not exist
data = open("data.txt").read()

TODOs sind während der Entwicklung nützlich, sollten jedoch mit einem Issue-Tracker verknüpft sein und nicht auf unbestimmte Zeit im Produktionscode verbleiben.

2. Große Blöcke auskommentieren statt zu löschen

Versionskontrolle (Git) bewahrt die Geschichte. Es ist nicht nötig, auskommentierten Code für die Nachwelt zu behalten — lösche ihn und verlasse dich auf git log, wenn du ihn jemals zurückbrauchst.

3. Inkonsistenter Stil

Eine Mischung aus #comment, # comment und ## comment in derselben Datei lässt die Codebasis unbesessen wirken. Einige dich auf einen Stil und wende ihn konsequent an.

Zusammenfassung

Kommentare sind ein leichtgewichtiges Werkzeug, das sich auszahlt, wann immer ein anderer Entwickler (oder du selbst in der Zukunft) deinen Code liest. Für weiterführende Lektüre zu verwandten Themen, siehe Python Syntax und Python Variables.

Practice