Wo werden die Sauerstoffkommentarblöcke für eine interne Bibliothek abgelegt - in H- oder in CPP-Dateien? [geschlossen]

Der gesunde Menschenverstand sagt, dass die Doxygen-Kommentarblöcke in die Header-Dateien eingefügt werden müssen, in denen sich die Klassen, Strukturen, Aufzählungen, Funktionen und Deklarationen befinden. Ich bin damit einverstanden, dass dies ein gutes Argument für Bibliotheken ist, die ohne ihre Quelle verteilt werden sollen (nur Header und Bibliotheken mit Objektcode).

ABER ... Ich habe über den genau entgegengesetzten Ansatz nachgedacht, als ich eine unternehmensinterne (oder als Nebenprojekt für mich selbst) Bibliothek entwickelt habe, die mit ihrem vollständigen Quellcode verwendet wird. Ich schlage vor, die großen Kommentarblöcke in die Implementierungsdateien (HPP, INL, CPP usw.) einzufügen, um die Schnittstelle der im Header deklarierten Klassen und Funktionen NICHT zu überladen.

Vorteile:

• Weniger Unordnung in den Header-Dateien, nur eine Kategorisierung der Funktionen kann hinzugefügt werden.
• Die Kommentarblöcke, die bei Verwendung von Intellisense in der Vorschau angezeigt werden, kollidieren nicht. Dies ist ein Fehler, den ich festgestellt habe, wenn ich einen Kommentarblock für eine Funktion in der .H-Datei habe und dessen Inline-Definition in derselben .H-Datei liegt aber aus der INL-Datei enthalten.

Nachteile:

• (Der offensichtliche) Die Kommentarblöcke befinden sich nicht in den Header-Dateien, in denen sich die Deklarationen befinden.

Also, was denkst du und schlägst du möglicherweise vor?

Legen Sie die Dokumentation dort ab, wo die Benutzer sie lesen und schreiben, während sie den Code verwenden und daran arbeiten.

Klassenkommentare stehen vor Klassen, Methodenkommentare vor Methoden.

Das ist der beste Weg, um sicherzustellen, dass die Dinge erhalten bleiben. Es hält auch Ihre Header - Dateien relativ mager und vermeidet die berührende Frage der Menschen zu aktualisieren Methode docs verursacht Header schmutzig und das Auslösen Neuaufbaus sein. Ich habe tatsächlich gewusst, dass Leute das als Ausrede benutzen, um später Dokumentation zu schreiben !

Ich nutze gerne die Tatsache, dass Namen an mehreren Stellen dokumentiert werden können.

In die Header-Datei schreibe ich eine kurze Beschreibung der Methode und dokumentiere alle ihre Parameter - diese ändern sich weniger wahrscheinlich als die Implementierung der Methode selbst, und wenn dies der Fall ist, muss der Funktionsprototyp auf jeden Fall geändert werden .

Ich habe langformatige Dokumentation in die Quelldateien neben der eigentlichen Implementierung eingefügt, damit die Details im Verlauf der Methode geändert werden können.

Beispielsweise:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Kommentare in der Kopfzeile bedeuten, dass alle Benutzer einer Klasse neu kompiliert werden müssen, wenn ein Kommentar geändert wird. Bei großen Projekten sind Programmierer weniger geneigt, Kommentare in Kopfzeilen zu aktualisieren, wenn sie die nächsten 20 Minuten damit verbringen, alles neu zu erstellen.

Und ... da Sie das HTML-Dokument lesen und nicht den Code nach Dokumentation durchsuchen sollen, ist es kein großes Problem, dass die Kommentarblöcke in den Quelldateien schwieriger zu finden sind.

Überschriften: Einfacheres Lesen der Kommentare, da beim Betrachten der Dateien weniger andere "Geräusche" auftreten.

Quelle: Dann stehen Ihnen die eigentlichen Funktionen zum Lesen zur Verfügung, während Sie sich die Kommentare ansehen.

Wir verwenden nur alle globalen Funktionen, die in Headern kommentiert sind, und lokale Funktionen, die in der Quelle kommentiert sind. Wenn Sie möchten, können Sie auch den Befehl copydoc einfügen, um die Dokumentation an mehreren Stellen einzufügen, ohne sie mehrmals schreiben zu müssen (besser für die Wartung).

Sie können die Ergebnisse jedoch auch mit einem einfachen Befehl in eine andere Dateidokumentation kopieren lassen. Z.B :-

Meine Datei1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MEINE Datei1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Jetzt erhalten Sie für beide Funktionen die gleiche Dokumentation.

Dies gibt Ihnen weniger Rauschen in den Codedateien, während Sie die Dokumentation an einer Stelle schreiben lassen, die an mehreren Stellen in der endgültigen Ausgabe dargestellt wird.

Normalerweise füge ich die Dokumentation für die Schnittstelle (\ param, \ return) in die .h-Datei und die Dokumentation für die Implementierung (\ details) in die .c / .cpp / .m-Datei ein. Doxygen gruppiert alles in der Funktions- / Methodendokumentation.

Ich habe alles in die Header-Datei eingefügt.

Ich dokumentiere alles, extrahiere aber generell nur die öffentliche Schnittstelle.

Ich benutze QtCreator zum Programmieren. Ein sehr nützlicher Trick besteht darin, bei gedrückter Strg-Taste auf eine Funktion oder Methode zu klicken, um die Deklaration in der Header-Datei abzurufen.

Wenn die Methode in der Header-Datei kommentiert ist, können Sie die gesuchten Informationen schnell finden. Für mich sollten sich Kommentare in der Header-Datei befinden!

In c ++ kann die Implementierung manchmal zwischen Header- und CPP-Modulen aufgeteilt werden. Hier scheint es sauberer, die Dokumentation in die Header-Datei einzufügen, da dies der einzige Ort ist, an dem alle öffentlichen Funktionen und Methoden garantiert sind.