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

Dokumentation in C++-Projekten: Die Kunst, mit dem zukünftigen Ich zu sprechen

Geben Sie es ehrlich zu: Wie oft haben Sie Ihren eigenen Code, den Sie vor einem halben Jahr geschrieben haben, geöffnet und sich wie ein Archäologe gefühlt, der antike Ruinen ausgräbt? In C++ ist dieses Problem besonders akut. Eine leistungsstarke, aber komplexe Sprache mit Templates, Smart Pointern und RAII kann jedes Projekt in ein Rätsel verwandeln, wenn man nicht die besten Praktiken der C++-Dokumentation beachtet.

In diesem Artikel werden wir untersuchen, wie man C++-Code richtig dokumentiert, damit er nicht nur für den Compiler, sondern auch für Menschen verständlich ist. Sie erfahren, welche Tools Sie verwenden sollten, wie Sie selbstdokumentierenden Code schreiben und wie Sie typische Fehler vermeiden, die die Dokumentation in bedeutungsloses Rauschen verwandeln.

Warum C++-Dokumentation nicht nur „unnötige Arbeit“ ist

Viele Entwickler betrachten Dokumentation als notwendiges Übel: „Der Code spricht für sich selbst!“ – verkünden sie und hinterlassen eine Klasse Foo mit einer Methode bar(). Aber sehen wir der Wahrheit ins Auge: Dokumentation von C++-Projekten ist eine Investition. Sie zahlt sich aus, wenn:

\n
• Sie nach einem Monat zum Projekt zurückkehren.
\n
• Ein neuer Entwickler zum Team stößt.
\n
• Sie einen Fehler in fremdem (oder eigenem) Code suchen.
\n
• Die API einer Bibliothek von externen Nutzern verwendet wird.
\n

Studien zeigen, dass Entwickler bis zu 60% ihrer Zeit damit verbringen, vorhandenen Code zu verstehen. Gute Dokumentation verkürzt diese Zeit um ein Vielfaches. Aber wie macht man sie wirklich nützlich?

Dokumentationswerkzeuge: Doxygen und mehr

In der Welt von C++ ist der De-facto-Standard Doxygen. Dieses Tool parst spezielle Kommentare und generiert daraus HTML, PDF, LaTeX und andere Formate. Sehen wir uns an, wie das funktioniert.

Grundlegende Doxygen-Syntax

Doxygen unterstützt mehrere Kommentarstile. Hier sind die gängigsten:

/**\n * @brief Kurzbeschreibung der Klasse.\n * \n * Die detaillierte Beschreibung kann mehrere Absätze umfassen.\n * Hier kann erklärt werden, wie die Klasse funktioniert und wie sie verwendet wird.\n * \n * @tparam T Datentyp für die Speicherung.\n */\ntemplate <typename T>\nclass MyContainer {\npublic:\n    /**\n     * @brief Fügt ein Element am Ende des Containers hinzu.\n     * \n     * @param value Konstanter Verweis auf das hinzuzufügende Element.\n     * @return true, wenn das Element erfolgreich hinzugefügt wurde.\n     * @return false, wenn der Container voll ist.\n     */\n    bool push_back(const T& value);\n    \nprivate:\n    T* data_;\n    size_t size_;\n    size_t capacity_;\n};

Wichtige Doxygen-Tags:

\n
• @brief — Kurzbeschreibung (wird in der Übersicht angezeigt).
\n
• @param — Beschreibung des Funktionsparameters.
\n
• @return — Beschreibung des Rückgabewerts.
\n
• @tparam — Beschreibung des Template-Parameters.
\n
• @note — Wichtiger Hinweis.
\n
• @warning — Warnung.
\n
• @see — Verweis auf verwandten Code.
\n

Alternativen zu Doxygen

Obwohl Doxygen der König ist, gibt es auch andere Tools:

\n
• Sphinx mit der Breathe-Erweiterung – für Liebhaber des Python-Ökosystems.
\n
• Standardese – ein moderner Dokumentationsgenerator mit Markdown-Syntax.
\n
• Moxygen – konvertiert Doxygen in Markdown.
\n

Aber für die meisten Projekte bleibt Doxygen aufgrund seiner Reife und Flexibilität die optimale Wahl.

Dokumentation schreiben, die gelesen wird

Kommen wir nun zum Wichtigsten: Wie schreibt man Dokumentation von C++-Code, die nützlich ist und nicht nur eine formale Befüllung von Tags darstellt.

Regel 1: Kommentieren Sie das „Warum“, nicht das „Was“

Der häufigste Fehler von Anfängern ist es, Offensichtliches zu kommentieren. Sehen Sie sich dieses Beispiel an:

// Schlecht: Der Kommentar liefert keine Information\nint x = 5; // Weist der Variable x den Wert 5 zu\n\n//