JavaScript-Kommentare

Einführung

Dieses Kapitel behandelt alles, was du brauchst, um gute JavaScript-Kommentare zu schreiben: die zwei Kommentarsyntaxen (// für Zeilenkommentare und /* */ für Blockkommentare), JSDoc-Kommentare zur Dokumentation von Funktionen, den Unterschied zwischen hilfreichen und schädlichen Kommentaren sowie das Auskommentieren von Code beim Debuggen. Kommentare sind Text, den die JavaScript-Engine während der Ausführung vollständig ignoriert — sie existieren ausschließlich für Menschen. Sie erklären deinen Code jedem, der ihn später liest, einschließlich deines zukünftigen Ichs und deiner Teammitglieder. Da sie aus der Ausführung entfernt werden, verursachen Kommentare keine Laufzeitkosten. (Eine verwandte Direktive, die tatsächlich von der Engine gelesen wird, ist "use strict"; obwohl sie wie ein String am Anfang einer Datei aussieht, ändert sie das Verhalten des Codes — siehe das Kapitel zum Strict-Modus.)

Warum Kommentare in JavaScript unverzichtbar sind

Kommentare mögen nebensächlich erscheinen, spielen aber eine entscheidende Rolle beim Programmieren. Sie helfen bei:

• Code-Dokumentation: Zur Erklärung komplexer Logik oder der Begründung hinter bestimmten Code-Abschnitten.
• Code-Lesbarkeit: Zur Verbesserung des Verständnisses des Code-Ablaufs und der Funktionalität.
• Debugging: Zum einfachen Aktivieren oder Deaktivieren von Code-Teilen während des Testens oder Debuggens.
• Teamarbeit: Zur Unterstützung anderer Entwickler beim Verstehen deines Denkprozesses.

Arten von JavaScript-Kommentaren

JavaScript unterstützt zwei Hauptarten von Kommentaren:

Einzeilige Kommentare

Einzeilige Kommentare beginnen mit // und reichen bis zum Ende der aktuellen Zeile. Alles nach // in dieser Zeile wird ignoriert. Sie können in einer eigenen Zeile stehen oder am Ende einer Code-Zeile (ein Inline-Kommentar):

// This whole line is a comment
let a = 5, b = 10;

let sum = a + b; // inline comment: add the two values

Da ein //-Kommentar nur bis zum Zeilenende reicht, ist die nächste Zeile wieder normaler Code — du musst ihn nicht „schließen".

Mehrzeilige Kommentare

Mehrzeilige Kommentare (auch Blockkommentare genannt) beginnen mit /* und enden mit */. Alles dazwischen wird ignoriert, auch über viele Zeilen hinweg. Verwende sie für längere Erklärungen:

/*
  Returns the sum of two numbers.
  Both arguments are expected to be numbers;
  passing strings will concatenate instead of add.
*/
function add(a, b) {
    return a + b;
}

Du kannst die Blocksyntax auch mitten in einer Zeile verwenden, zum Beispiel um ein Argument zu beschriften: setTimeout(run, 1000 /* ms */).

Achtung — Blockkommentare können nicht verschachtelt werden. Ein */ beendet den Kommentar beim ersten Auftreten. Das Einwickeln von Code, der bereits /* ... */ enthält, in einen weiteren Blockkommentar führt daher zu Fehlern. Das innere */ schließt den Kommentar vorzeitig, und der Rest wird zu ausführbarem Code:

/*
  /* inner */
  alert('this still runs!');
*/

Kopieren

Um einen Bereich auszukommentieren, der Blockkommentare enthält, verwende stattdessen // in jeder Zeile.

Gute vs. schlechte Kommentare: Erkläre das Warum, nicht das Was

Die wichtigste Regel: kommentiere das Warum, nicht das Was. Der Code sagt bereits, was er tut; ein guter Kommentar erfasst die Absicht, den Kompromiss oder die überraschende Einschränkung, die der Code selbst nicht ausdrücken kann.

// Bad: just restates the code — adds noise, can go stale
let total = 0; // set total to 0

// Good: explains a non-obvious constraint
const RETRY_LIMIT = 3; // the payment API rejects bursts above 3 calls/sec

Bevorzuge selbstdokumentierenden Code gegenüber Kommentaren, wo immer möglich. Eine gut benannte Variable oder eine kleine Funktion beseitigt oft die Notwendigkeit eines Kommentars vollständig:

// Needs a comment because the intent is hidden:
if (u.a && Date.now() - u.l < 86400000) { /* active in last 24h */ }

// No comment needed — the names say it:
const isActive = user.isVerified && wasSeenInLast24Hours(user);
if (isActive) {
  // ...
}

Einige weitere Leitlinien:

1. Halte sie aktuell. Ein Kommentar, der dem Code widerspricht, ist schlimmer als gar kein Kommentar — Leser können nicht erkennen, welchem sie vertrauen sollen.
2. Sei prägnant. Erkläre die Begründung, nicht jeden einzelnen Schritt.
3. Kommentiere toten Code nicht dauerhaft aus. Lösche ihn; die Versionsverwaltung erinnert sich daran.

Code auskommentieren

Beim Debuggen möchtest du oft eine Zeile oder einen Block deaktivieren, ohne ihn zu löschen. Stelle einer Zeile // voran oder umschließe einen Bereich mit /* */:

let value = compute();
// console.log('Debug:', value); // temporarily silenced

/*
expensiveLogging(value);
sendToAnalytics(value);
*/

Das ist ideal, um zu isolieren, welcher Teil des Codes ein Problem verursacht. Viele Editoren ermöglichen dies mit einem Tastaturkürzel. Siehe das Kapitel zur Console API für sauberere Alternativen zu verbliebenem console.log-Debugging.

TODO- und FIXME-Markierungen

Eine gängige Konvention ist es, unfertige Arbeit mit TODO (etwas, das später erledigt werden soll) oder FIXME (ein bekannter Fehler) zu kennzeichnen. Editoren und Linter können diese für dich auflisten:

// TODO: optimize this loop for large data sets
// FIXME: breaks when input is an empty array

JSDoc: Funktionen dokumentieren

JSDoc ist ein Standard zur Dokumentation von Funktionen mithilfe eines speziellen Blockkommentars, der mit /** (zwei Sternchen) beginnt. Tags wie @param und @returns beschreiben die Ein- und Ausgaben. Werkzeuge und Editoren lesen diese, um Inline-Hinweise anzuzeigen und HTML-Dokumentation zu generieren.

/**
 * Adds two numbers together.
 * @param {number} a - The first addend.
 * @param {number} b - The second addend.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

console.log(add(2, 3)); // 5

JSDoc passt besonders gut zu Funktionen: Das Dokumentieren von Parametern und Rückgabetypen macht den Vertrag einer Funktion klar, ohne ihren Körper lesen zu müssen. Weitere häufig verwendete Tags sind @throws, @example und @deprecated.

Fazit

Effektive Kommentare in JavaScript einzusetzen ist nicht nur eine Programmierpraktik, sondern eine Kommunikationsfähigkeit. Sie trägt erheblich zur Wartbarkeit und Skalierbarkeit von Code bei. Indem du JavaScript-Kommentare beherrschst, verbesserst du nicht nur deinen Code, sondern steigerst auch deine Zusammenarbeit mit anderen im Entwicklungsprozess.

Denke daran: gut kommentierter Code ist ein Zeichen eines durchdachten und professionellen Entwicklers. Nutze die Kraft der Kommentare und beobachte, wie dein JavaScript-Code zu einem zugänglicheren und wartbareren Werkzeug wird.

Übung