Dokumentation in JavaScript: Wie man Code schreibt, der für sich selbst spricht

Warum Dokumentation keine langweilige Pflicht, sondern eine Superkraft des Entwicklers ist

Stellen Sie sich vor: Sie öffnen ein fremdes (oder Ihr eigenes drei Monate altes) JavaScript-Projekt. Die Dateien sind voll mit Pfeilfunktionen, async/await und Destrukturierung. Aber warum heißt diese Funktion transformData? Was nimmt sie entgegen? Und vor allem – wozu wird sie benötigt, wenn es daneben processArray gibt?

Wenn Sie sich schon einmal dabei ertappt haben: „Ich erinnere mich nicht, was hier passiert“, dann ist dieser Artikel für Sie. Dokumentation in JavaScript geht nicht um langweilige Textabsätze. Es geht um Respekt vor Ihrem zukünftigen Ich und Ihren Kollegen. Es geht um die Geschwindigkeit des Einstiegs in ein Projekt und die Reduzierung der Fehleranzahl. In diesem Artikel behandeln wir die besten Praktiken zur Dokumentation von JS-Code: von JSDoc bis zur Generierung einer vollständigen Dokumentation.

JavaScript-Code-Dokumentation: Die Philosophie des „sprechenden Codes“

Bevor Sie Kommentare schreiben, ist es wichtig zu verstehen: Der beste Kommentar ist der, der nicht benötigt wird. Idealer Code sollte sich selbst erklären. Wie erreicht man das?

Benennung von Variablen und Funktionen

Schlechtes Beispiel:

// Schlecht\nconst x = 10; // was ist x?\nfunction d(a, b) { return a * b; } // was macht d?\n

Gutes Beispiel:

// Gut\nconst MAX_RETRY_COUNT = 10;\nfunction calculateDiscountedPrice(price, discountPercent) {\n  return price * (1 - discountPercent / 100);\n}\n

Verwenden Sie vollständige, aussagekräftige Namen. Benennen Sie Funktionen mit Verben (getUser, validateEmail), Variablen mit Substantiven (userList, isActive). Dies ist die Grundlage für selbstdokumentierenden Code.

Wann Kommentare dennoch notwendig sind

\n
• Komplexe Geschäftslogik: z.B. die Berechnung von Steuern nach einer nicht offensichtlichen Formel.
\n
• Hack oder temporäre Lösung: markieren Sie es mit TODO oder FIXME.
\n
• Warum genau dieser Ansatz gewählt wurde: Es gab Alternativen, aber dieser ist optimal in Bezug auf die Geschwindigkeit.
\n
• Beschreibung der öffentlichen API: damit andere Entwickler wissen, wie sie Ihre Funktion aufrufen können.
\n

JSDoc: Der Standard für die JavaScript-Dokumentation

JSDoc ist eine Syntax zum Schreiben von Dokumentation direkt im Code, die von Editoren (VS Code, WebStorm) und Generierungswerkzeugen verstanden wird. Es ist ein Must-have für jedes ernsthafte Projekt.

Grundlegende Annotation einer Funktion

/**\n * Berechnet den Endpreis einer Bestellung unter Berücksichtigung von Rabatt und Steuer.\n * @param {number} price - Der Grundpreis des Artikels.\n * @param {number} discount - Der Rabatt in Prozent (0-100).\n * @param {number} taxRate - Der Steuersatz in Prozent (0-100).\n * @returns {number} Der Endpreis.\n */\nfunction calculateTotal(price, discount, taxRate) {\n  const discountedPrice = price * (1 - discount / 100);\n  return discountedPrice * (1 + taxRate / 100);\n}\n

Wenn Sie nun im Editor mit der Maus über die Funktion calculateTotal fahren, sehen Sie deren Beschreibung, Parameter und Rückgabewert. Magie!

Annotationen für Objekte und Typen

/**\n * @typedef {Object} User\n * @property {number} id - Die eindeutige Kennung.\n * @property {string} name - Der Name des Benutzers.\n * @property {boolean} isActive - Ob das Konto aktiv ist.\n */\n\n/**\n * Ruft die Liste der aktiven Benutzer ab.\n * @param {User[]} users - Ein Array von Benutzern.\n * @returns {User[]} Das gefilterte Array.\n */\nfunction getActiveUsers(users) {\n  return users.filter(user => user.isActive);\n}\n

Die Verwendung von @typedef ermöglicht es, eigene Typen zu erstellen, was den Code lesbar und sicher macht. Dies ist besonders nützlich in Projekten ohne TypeScript.

Dokumentation asynchroner Funktionen

/**\n * Lädt Benutzerdaten vom Server.\n * @async\n * @param {number} userId - Die ID des Benutzers.\n * @returns {Prom