it-swarm.dev

Ist es besser, Funktionen in der Header-Datei oder der Quelldatei zu dokumentieren?

In Sprachen, die zwischen einer "Quell" - und einer "Header" -Datei unterscheiden (hauptsächlich C und C++), ist es besser, Funktionen in der Header-Datei zu dokumentieren:

(gestohlen von CCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since Epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

oder in der Quelldatei?

(gestohlen von PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

Beachten Sie, dass einige Dinge nur im Header definiert sind, z. B. Strukturen, Makros und static inline Funktionen. Ich spreche nur von Dingen, die in einer Header-Datei deklariert und definiert sind in einer Quelldatei.

Hier sind einige Argumente, die mir einfallen. Ich neige dazu, in der Quelldatei zu dokumentieren, daher sind meine "Pro-Header" -Argumente möglicherweise etwas schwach.

Pro-Header:

  • Der Benutzer benötigt den Quellcode nicht, um die Dokumentation anzuzeigen.
    • Die Quelle kann unbequem oder sogar unmöglich zu beschaffen sein.
    • Dies hält Schnittstelle und Implementierung weiter voneinander entfernt.

Pro-Quelle:

  • Dadurch wird der Header viel kürzer und der Leser kann das Modul als Ganzes aus der Vogelperspektive betrachten.
  • Es koppelt die Dokumentation einer Funktion mit ihrer Implementierung, sodass leichter erkennbar ist, dass eine Funktion das tut, was sie verspricht.

Seien Sie bei der Beantwortung vorsichtig mit Argumenten, die darauf basieren, was Tools und "moderne IDEs" können. Beispiele:

  • Pro-Header: Durch das Falten von Code können kommentierte Header besser navigiert werden, indem die Kommentare ausgeblendet werden.
  • Pro-Quelle: cscope 's Find this global definition Funktion führt Sie zur Quelldatei (wo die Definition ist) und nicht zur Header-Datei (wo die Deklaration ist).

Ich sage nicht, dass Sie solche Argumente nicht vorbringen, aber denken Sie daran, dass nicht jeder mit den von Ihnen verwendeten Werkzeugen so vertraut ist wie Sie.

94
Joey Adams

Meine Sicht...

  • Dokumentieren Sie, wie die Funktion in der Header-Datei oder genauer in der Nähe der Deklaration verwendet wird.

  • Dokumentieren Sie in der Quelldatei oder genauer in der Nähe der Definition, wie die Funktion funktioniert (wenn dies aus dem Code nicht ersichtlich ist).

Für die Vogelperspektive in der Kopfzeile benötigen Sie nicht unbedingt die Dokumentation, die geschlossen wird - Sie können Gruppen von Deklarationen gleichzeitig dokumentieren.

Im Großen und Ganzen sollte der Anrufer an Fehlern und Ausnahmen interessiert sein (wenn nur, damit sie übersetzt werden können, wenn sie sich durch die Abstraktionsebenen ausbreiten), sodass diese in der Nähe der relevanten Erklärungen dokumentiert werden sollten.

101
Steve314

Wenn Sie ein Tool wie Doxygen verwenden (beachten Sie im ersten Beispiel, dass es wirklich wie ein Doxygen-Kommentar aussieht, da es mit /** Beginnt), dann nicht wirklich Angelegenheit - Doxygen durchsucht Ihre Header- und Quelldateien und findet alle Kommentare, um die Dokumentation zu generieren.

Ich wäre jedoch eher geneigt, die Dokumentationskommentare in die Überschriften zu setzen, in denen sich die Erklärungen befinden. Ihre Kunden werden sich mit den Headern befassen, um eine Schnittstelle zu Ihrer Software herzustellen. Die Header sind das, was sie in ihre eigenen Quelldateien aufnehmen, und dort werden sie zuerst nachsehen, wie Ihre API aussieht.

Wenn Sie sich zum Beispiel die meisten Linux-Bibliotheken ansehen, enthält Ihr Linux-Paketverwaltungssystem häufig ein Paket, das nur die Binärdateien der Bibliothek enthält (für "normale" Benutzer, die Programme haben, die die Bibliothek benötigen), und Sie haben ein "dev" -Paket, das enthält die Header für die Bibliothek. Der Quellcode wird normalerweise nicht direkt in einem Paket geliefert. Es wäre sehr umständlich, wenn Sie den Quellcode einer Bibliothek irgendwo abrufen müssten, um die Dokumentation der API zu erhalten.

35
Jesper

Wir haben dieses Problem (vor ungefähr 25 Jahren) gelöst, indem wir eine Reihe von #Definitionen (z. B. öffentlich, privat usw., die in <nichts> aufgelöst wurden) erstellt haben, die in der Quelldatei verwendet werden konnten und von einem awk-Skript gescannt wurden (Horror) !), um die .h-Dateien automatisch zu generieren. Dies bedeutet, dass alle Kommentare in der Quelle gespeichert und (falls zutreffend) in die generierte .h-Datei kopiert wurden. Ich weiß, dass es ziemlich altmodisch ist, aber es hat diese Art von Inline-Dokumentation erheblich vereinfacht.

12
Peter Rowell

Angenommen, dies ist Code in einem größeren Projekt (wo Entwickler häufig zwischen Quelle und Header wechseln) , und dies wird bereitgestellt nicht eine Bibliothek/Middleware, in der andere möglicherweise keinen Zugriff auf die Quelle haben. Ich habe festgestellt, dass dies am besten funktioniert ...

  • Überschriften:
    Knappe 1-2 Zeilen Kommentare, nur wenn sie benötigt werden.
    Manchmal sind auch Kommentare über einer Gruppe verwandter Funktionen hilfreich.
  • Quelle:
    Dokumentation zur API direkt über der Funktion (Klartext oder Sauerstoff, wenn Sie dies bevorzugen) .
  • Behalten Sie Implementierungsdetails bei, die nur für Entwickler relevant sind, die den Code im Hauptteil der Funktion ändern.

Der Hauptgrund dafür ist, dass die Kommentare nahe am Code bleiben. Ich habe festgestellt, dass Dokumente in den Headern häufiger nicht mehr mit Änderungen am Code synchronisiert werden (natürlich sollten sie nicht). t, aber sie haben es zumindest in unserem Projekt getan) . Entwickler können auch Dokumentation am Anfang von Funktionen hinzufügen, wenn sie Änderungen vornehmen, selbst wenn sich Dokumente in der Kopfzeile befinden, was dazu führt, dass Double-Ups oder nützliche Informationen nur in einer der Dokumentzeichenfolgen enthalten sind.

Natürlich können Sie eine Konvention auswählen und sicherstellen, dass alle Entwickler folgen. Ich habe gerade festgestellt, dass die Konvention über der höchsten natürlichen Passform liegt und die geringsten Probleme bei der Wartung verursacht.


Zu guter Letzt gibt es bei großen Projekten die Neigung nicht, kleine Korrekturen in einem Header vorzunehmen, wenn Sie wissen, dass möglicherweise 100 oder 1000 Dateien neu kompiliert werden, wenn andere die Versionskontrolle aktualisieren. Verlangsamung von Halbierungsfehlern ebenfalls.

9
ideasman42

Kommentare sind keine Dokumentation. Die Dokumentation für eine Funktion besteht normalerweise aus 2 KB Text, möglicherweise mit Diagrammen. Siehe beispielsweise die Dokumentation zu Funktionen im Windows SDK. Selbst wenn Ihr Kommentar-zu-Dokument so etwas zulässt, machen Sie den Code, der den Kommentar enthält, unlesbar. Wenn Sie Dokumentation erstellen möchten, verwenden Sie ein Textverarbeitungsprogramm.

6

Meiner (eher begrenzten und voreingenommenen) Meinung nach bin ich eine Pro-Source-Code-Denkweise. Wenn ich in C++ Kleinigkeiten mache, bearbeite ich die Header-Datei normalerweise einmal und gehe dann nie wirklich zurück, um sie mir anzusehen.

Wenn ich Dokumentation in die Quelldatei einfüge, wird sie beim Bearbeiten oder Lesen von Codes immer angezeigt. Ich denke, es ist eine Gewohnheit.

Aber das bin nur ich ...

5
MattyD

Wenn die Stakeholder Ihres Quellcodes (z. B. eine kleine Bibliothek) aus "Benutzern" (Mitentwicklern, die die Funktionalität Ihrer Bibliothek nutzen, ohne sich an deren Implementierung zu beteiligen) und "Entwicklern" (Sie und andere Entwickler, die die Bibliothek implementieren) bestehen, Fügen Sie dann die "Benutzerinformationen" in den Header und den "Implementierungshinweis" in die Quelle ein.

In Bezug auf den Wunsch, die Header-Dateien nicht mehr als unbedingt erforderlich zu ändern - ich nehme an, wenn sich Ihre Bibliothek nicht "in einem verrückten Fluss von Änderungen" befindet, werden sich die "Schnittstelle" und die "Funktion" nicht wesentlich ändern, und auch nicht sollten sich die Header-Kommentare zu häufig ändern. Andererseits müssen Quellcodekommentare mit dem Quellcode synchronisiert ("frisch") gehalten werden.

4
rwong

Der springende Punkt bei der Verwendung von Sauerstoff ist, dass Sie generieren Dokumentation und sie an einer anderen Stelle zugänglich machen. Jetzt ist die gesamte Dokumentation in den Headern nur noch Müll, was es schwieriger macht, die erforderliche Funktionsdeklaration und möglicherweise ihre Überladungen schnell zu erkennen. Ein Liner-Kommentar ist maximal, der dorthin gehen sollte, aber selbst das ist eine schlechte Praxis. Ursache Wenn Sie die Dokumentation in der Quelle ändern, kompilieren Sie diese Quelle neu und verknüpfen sie erneut. Wenn Sie jedoch Dokumente in den Header einfügen, möchten Sie dort nicht die geringste Änderung vornehmen, da dies einen erheblichen Teil der Projektwiederherstellung auslösen wird.

0
Slava