Schreiben von Dokumentation für C++-Projekte: von A bis Z

Online Python-Trainer für Anfänger

Lernen Sie Python einfach ohne theoretische Überlastung. Lösen Sie praktische Aufgaben mit automatischer Überprüfung und schreiben Sie Code direkt im Browser.

Kurs starten

Einleitung: Warum Dokumentation kein Luxus, sondern eine Notwendigkeit ist

Jeder C++-Entwickler stößt früher oder später auf die Situation, dass der eigene, vor einem halben Jahr geschriebene Code fremd erscheint. Ohne qualitativ hochwertige Dokumentation wird ein Projekt zu einer "Black Box", in der selbst der Autor Stunden damit verbringt, die Logik wiederherzustellen. In der Teamarbeit verlangsamt fehlende Dokumentation das Onboarding neuer Teammitglieder und erhöht die Anzahl der Fehler.

In diesem Artikel werden wir den gesamten Zyklus der Erstellung von Dokumentation für ein C++-Projekt durchgehen: von der Auswahl der Werkzeuge bis zur automatischen Generierung. Sie erfahren, wie Sie Kommentare schreiben, die sowohl für Menschen als auch für Doxygen nützlich sind, wie Sie die Dokumentation strukturieren und welche Best Practices Sie anwenden, damit Ihr Projekt zum Maßstab für Lesbarkeit wird.

1. Werkzeugauswahl: Doxygen als Industriestandard

Für C++ gibt es mehrere Werkzeuge zur Dokumentationsgenerierung, aber Doxygen bleibt der unangefochtene Marktführer. Es unterstützt C, C++, C#, Python, Java und generiert Dokumentation in HTML, LaTeX, PDF, RTF und sogar Man-Seiten.

Installation und grundlegende Konfiguration

Installieren Sie Doxygen über den Paketmanager:

# Ubuntu/Debiansudo apt install doxygen doxygen-gui

# macOSbrew install doxygen

# Windows (über chocolatey)choco install doxygen.install

Erstellen Sie eine Konfigurationsdatei:

doxygen -g Doxyfile

Bearbeiten Sie die wichtigsten Parameter in der Doxyfile:

PROJECT_NAME — Name Ihres Projekts
OUTPUT_DIRECTORY — Ordner für die generierte Dokumentation
INPUT — Pfade zu den Quelldateien
RECURSIVE = YES — Rekursives Durchsuchen von Ordnern
EXTRACT_ALL = YES — Auch undokumentierte Elemente dokumentieren
GENERATE_LATEX = YES — Für die PDF-Generierung

2. Regeln für Code-Kommentare: Vom Einfachen zum Komplexen

Doxygen unterstützt zwei Kommentarstile: Javadoc (Blockkommentare) und Qt-Stil (einzeilig). Für C++ wird der Javadoc-Stil empfohlen.

Basis-Kommentare für Klassen und Funktionen

/** * @brief Klasse für die Arbeit mit mathematischen Vektoren im 3D-Raum. *  * Unterstützt grundlegende Operationen: Addition, Subtraktion, Skalarprodukt. * Alle Operationen werden mit doppelter Genauigkeit (double) ausgeführt. *  * @author Ivan Ivanov * @version 1.0 * @date 2024-01-15 */class Vector3D {public:    /**     * @brief Konstruktor aus drei Koordinaten.     * @param x X-Koordinate.     * @param y Y-Koordinate.     * @param z Z-Koordinate.     */    Vector3D(double x, double y, double z);

    /**     * @brief Berechnet die Länge des Vektors.     * @return Länge des Vektors (Norm).     *      * @code     * Vector3D v(3.0, 4.0, 0.0);     * double len = v.length(); // len == 5.0     * @endcode     */    double length() const;};

Dokumentation von Templates und Überladungen

/** * @brief Allgemeine Vergleichsfunktion. * @tparam T Typ der zu vergleichenden Objekte. Muss den Operator < unterstützen. * @param a Erstes Objekt. * @param b Zweites Objekt. * @return true, wenn a < b, sonst false. */template<typename T>bool lessThan(const T& a, const T& b);

/** * @brief Spezialisierung für C-Strings. * @param a Erster String. * @param b Zweiter String. * @return true, wenn strcmp(a, b) < 0. */template<>bool lessThan<const char*>(const char* a, const char* b);

Dokumentation von Makros und Defines

/** * @def MAX_BUFFER_SIZE * @brief Maximale Puffergröße in Bytes. *  * Der Wert wurde mit 4096 Bytes für eine optimale Socket-Arbeit gewählt. */#define MAX_BUFFER_SIZE 4096