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

97

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?

Singulus
quelle

Antworten:

77

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 !

Andy Dent
quelle
11
Ich hatte eine schmerzhafte Erinnerung daran, warum Dokumente in Kopfzeilen vermieden werden sollten - wurde von einem leitenden Vizepräsidenten angewiesen, Methodenkommentare in die Klassendeklaration aufzunehmen, und fand mich dabei, Kommentaränderungen für später aufzubewahren, da das Schlagen dieser Kopfzeilen eine Erstellungszeit von 45 Minuten auslöst !
Andy Dent
7
Kein Downvoting, nur Fragen: Wenn ich herausfinden möchte, was eine API (auch eine interne) tut, muss ich lieber nicht die .cpp öffnen und den gesamten Code durchblättern, um die Dokumentation zu finden. Ich gebe zu, es wäre schmerzhaft, wenn Sie mehr als nur die Sicht des Kunden auf die Funktionsweise der Methode dokumentieren ( wie sie funktioniert), aber Sie sollten das trotzdem nicht tun, oder?
TED
8
Wenn Sie Doxygen zum Generieren Ihrer Dokumentation verwenden möchten, müssen Sie auf die generierte Dokumentation zugreifen können. Wir haben einen internen Webserver, auf dem die Doxygen-Ausgabe gespeichert wird, und wir können dann in Diskussionen Links zu Seiten auf diesem Server verwenden. Dies verbindet auch die Klassen- oder Methodendokumentation mit zusätzlichen Seiten, auf denen umfassendere Entwurfsprobleme erörtert werden.
Andy Dent
1
Die Entscheidung, wie öffentlich die Umsetzungsdiskussion sein soll, ist ein interessantes Thema. Wenn es einen bestimmten Algorithmus oder Nebenwirkungen gibt, würde ich sie als Client der Bibliothek lieber kennen. Manchmal sollte nur der Betreuer Bescheid wissen, und Doxygen hat eine einfache Möglichkeit, bedingte Abschnitte zu markieren, sodass Sie möglicherweise unterschiedliche Dokumente für unterschiedliche Sichtweisen generieren können.
Andy Dent
76

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;
}
Daniel Buckmaster
quelle
3
Ich mag diese Methode, aber sie scheint mit AUTOBRIEF nicht kompatibel zu sein. Es würde mich interessieren, ob es eine Konfigurationsumgehung gibt, um die mehreren produzierten Briefs zu eliminieren.
Aaron Wright
Ich mag diese Methode auch, sie bietet ein gutes Gleichgewicht bei der Implementierung.
Xofo
Ich kann diese Methode mit Doxygen 1.8.15 nicht auf meinem Computer reproduzieren. Die Parameterdokumentation wird nicht angezeigt, nur die kurzen und detaillierten Beschreibungen.
Punyidea
1
Nachtrag: Durch Ändern der Platzierung der detaillierten Beschreibung innerhalb des Funktionsblocks funktionierte dies für mich. Die Beschreibung wird jetzt an das Ende der Beschreibungen in den Header-Dokumenten angehängt.
Punyidea
18

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.


quelle
Richtig, aber es ist ein großes Problem, wenn es sich um eine dynamische Bibliothek handelt, die aus einem Artefakt abgerufen wurde und Sie nicht über die Quelldateien verfügen :-)
DrumM
12

Ü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.

eaanon01
quelle
2
Wann wird der Block kopiert?
Mert Can Ergün
2

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.

Mouviciel
quelle
2

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

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

graham.reeds
quelle
2

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!

Sinclair
quelle
-1

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.

Kelvin
quelle