Kommentar (im Code)

Ein Kommentar ist Text im Quelltext, den der Rechner überspringt. Er steht dort für die Menschen, die später hineinsehen.

Kommentar

Ein Abschnitt im Quelltext, der von der Ausführung ausgenommen ist und der Erklärung dient.
Beispiel: „Der Kommentar erklärt, warum die Berechnung hier von der sonstigen Regel abweicht.“

Abgrenzung zum auskommentierten Code: Code, der nur stillgelegt wurde, ist kein Kommentar im eigentlichen Sinn. Er gehört gelöscht; die Versionsverwaltung hebt ihn auf.

Warum statt was

Ein Kommentar, der wiederholt, was ohnehin dasteht, hilft niemandem und veraltet beim ersten Ändern. Wertvoll ist die Begründung: warum diese Lösung und nicht die naheliegende, welche Fundstelle die Regel vorgibt, welcher Sonderfall hier abgefangen wird.

Der gute Test lautet: Würde jemand beim Lesen stutzen? Dann gehört ein Satz dazu. Ist die Zeile selbsterklärend, bleibt sie unkommentiert.

// schlecht: wiederholt nur die Zeile
// addiert 1 zum Zähler
zaehler++;

// gut: erklärt eine Abweichung
// Der Versand nach Österreich wird pauschal berechnet,
// weil der Carrier dort keine Staffelpreise liefert.
versand = PAUSCHALE_AT;

Die Schreibweisen in den Sprachen

Zwei Formen kehren überall wieder: eine, die bis zum Zeilenende gilt, und eine, die über beliebig viele Zeilen geht. Welche Zeichen davor stehen, ist von Sprache zu Sprache verschieden.

<!-- HTML kennt nur diese eine Form.
     Sie darf über mehrere Zeilen gehen. -->

/* CSS ebenfalls nur diese eine Form,
   auch über mehrere Zeilen. */
.preis { color: red; }

// JavaScript: bis zum Zeilenende
/* und über mehrere
   Zeilen hinweg */
const preis = 19.99; // auch hinter Code

// PHP: bis zum Zeilenende
# ebenfalls bis zum Zeilenende, heute selten benutzt
/* und über mehrere Zeilen */

/**
 * Drei Sterne am Anfang: ein Dokumentationsblock.
 * Editoren lesen ihn aus und zeigen ihn beim Aufruf an.
 */

Die Template-Sprachen haben eigene Zeichen, und das hat einen Grund: Ihre Kommentare verschwinden beim Erzeugen der Seite, während ein HTML-Kommentar an derselben Stelle beim Besucher ankäme.

{{# Antlers (Statamic) #}}
{# Twig (TYPO3, Symfony, Craft) #}
{{-- Blade (Laravel) --}}

# YAML und die Kommandozeile: das Doppelkreuz
-- SQL: zwei Bindestriche

Eine Sprache fehlt in der Aufzählung mit Absicht: JSON kennt keine Kommentare. Wer dort etwas anmerken will, legt ein Feld mit einem Namen wie _kommentar an, das die auswertende Stelle übergeht.

Der Kommentar, der nicht mehr stimmt

Code wird geändert, der Kommentar daneben oft nicht. Dann steht dort eine Aussage, die einmal richtig war, und schickt den nächsten Leser in die falsche Richtung. Ein falscher Kommentar ist schlechter als gar keiner.

Deshalb gilt die Faustregel, sparsam und gezielt zu kommentieren. Weniger Kommentare, die stimmen, sind mehr wert als viele, die gepflegt werden müssten.

Sichtbar im Browser

Kommentare in HTML landen beim Besucher und sind im Quelltext der Seite zu lesen. Was dort nicht stehen soll, gehört nicht hinein: keine internen Hinweise, keine Adressen von Testumgebungen, keine Zugangsdaten.

Kommentare in CSS und JavaScript verschwinden meist beim Zusammenpacken für den Produktivbetrieb, aber darauf ist kein Verlass. In Server-Code bleiben sie ohnehin beim Server.