it-swarm.com.de

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

Der gesunde Menschenverstand sagt, dass die Doxygen-Kommentarblöcke in den Header-Dateien abgelegt 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 Quelle verteilt werden sollen (nur Header und Bibliotheken mit Objektcode).

ABER ... Ich habe über das genaue Gegenteil nachgedacht, als ich eine firmeninterne Bibliothek (oder als Nebenprojekt für mich) entwickelte, die mit dem 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 überfrachten.

Profis:

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

Nachteile:

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

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

91
Singulus

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 gepflegt werden. Es hält auch Ihre Header-Dateien relativ schlank und vermeidet das berührende Problem, dass Benutzer Methodendokumente aktualisieren, wodurch Header verschmutzt werden und Neuerstellungen ausgelöst werden. Ich habe tatsächlich gewusst, dass die Leute das als Ausrede für das Schreiben von Dokumentation benutzen später!

72
Andy Dent

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

In der 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 ja, muss der Funktionsprototyp in jedem Fall geändert werden .

Ich habe in den Quelldateien neben der eigentlichen Implementierung eine Langformatdokumentation abgelegt, damit die Details geändert werden können, wenn sich die Methode weiterentwickelt.

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;
}
65

Kommentare im Header 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 den Kopfzeilen zu aktualisieren, wenn sie riskieren, die nächsten 20 Minuten damit zu verbringen, alles neu aufzubauen.

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.

17
ErikJ

Header: Einfacheres Lesen der Kommentare, da beim Betrachten der Dateien weniger "Rauschen" auftritt.

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

Wir verwenden nur alle globalen Funktionen, die in Kopfzeilen 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. 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 zu beiden Funktionen die gleiche Dokumentation.

Dies führt zu weniger Rauschen in den Codedateien, während die Dokumentation an einer Stelle geschrieben und an mehreren Stellen in der endgültigen Ausgabe angezeigt wird.

11
eaanon01

Ich habe alles in die Header-Datei gestellt.

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

2
graham.reeds

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

2
mouviciel

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. Also für mich sollten sich Kommentare in der Header-Datei befinden!

1
Sinclair