Wo dokumentiert man Funktionen in C oder C++? [closed]

Ich habe ein C-Programm mit mehreren Dateien, also habe ich zum Beispiel stuff.c die einige Funktionen implementiert, und stuff.h mit den Funktionsprototypen.

Wie sollte ich vorgehen, um die Funktionen in Kommentaren zu dokumentieren?

Sollte ich alle Dokumente in der Header-Datei haben, alle Dokumente in der .c Datei oder duplizieren Sie die Dokumente für beide? Ich mag den letzteren Ansatz, aber dann stoße ich auf Probleme, bei denen ich die Dokumente auf einem von ihnen aktualisiere und nicht auf dem anderen (normalerweise das, wo ich die erste Änderung vornehme, dh wenn ich zuerst die Header-Datei ändere, dann ihre Kommentare wird dies widerspiegeln, aber wenn ich die Implementierung aktualisiere, werden sich nur diese Kommentare ändern).

Diese Frage und ihre Antworten gelten auch für C++-Code – siehe auch Wo soll ich Dokumentationskommentare einfügen?

• Fügen Sie die Informationen, die Personen, die die Funktionen verwenden, wissen müssen, in die Kopfzeile ein.

• Fügen Sie die Informationen, die Betreuer der Funktionen kennen müssen, in den Quellcode ein.

Ich folge gerne dem Google C++ Gestaltungsrichtlinie.

Was sagt:

Funktionsdeklarationen

• Jeder Funktionsdeklaration sollten Kommentare unmittelbar vorangestellt sein, die beschreiben, was die Funktion tut und wie sie verwendet wird. Diese Kommentare sollten eher beschreibend sein (“Öffnet die Datei”) als zwingend (“Öffne die Datei”); Der Kommentar beschreibt die Funktion, er sagt der Funktion nicht, was sie tun soll. Im Allgemeinen beschreiben diese Kommentare nicht, wie die Funktion ihre Aufgabe erfüllt. Stattdessen sollte dies Kommentaren in der Funktionsdefinition überlassen werden.

Funktionsdefinitionen

• Jede Funktionsdefinition sollte einen Kommentar haben, der beschreibt, was die Funktion tut und alles, was daran knifflig ist, wie sie ihre Arbeit macht. Im Definitionskommentar können Sie beispielsweise alle von Ihnen verwendeten Codierungstricks beschreiben, einen Überblick über die Schritte geben, die Sie durchlaufen, oder erklären, warum Sie sich entschieden haben, die Funktion so zu implementieren, wie Sie es getan haben, anstatt eine praktikable Alternative zu verwenden. Sie könnten beispielsweise erwähnen, warum für die erste Hälfte der Funktion eine Sperre erworben werden muss, für die zweite Hälfte jedoch nicht erforderlich ist.

  Beachten Sie, dass Sie die mit der Funktionsdeklaration gegebenen Kommentare nicht einfach in der .h-Datei oder wo auch immer wiederholen sollten. Es ist in Ordnung, kurz zu rekapitulieren, was die Funktion tut, aber der Fokus der Kommentare sollte darauf liegen, wie sie es tut.

Sie sollten ein Tool wie verwenden Sauerstoffsodass die Dokumentation durch speziell gestaltete Kommentare in Ihrem Quellcode generiert wird.

Ich bin hin und her gegangen und habe mich schließlich für die Dokumentation in Header-Dateien entschieden. Für die überwiegende Mehrheit der APIs in C/C++ haben Sie Zugriff auf die ursprüngliche Header-Datei und damit auf alle darin enthaltenen Kommentare [1]. Wenn Sie Kommentare hier platzieren, maximieren Sie die Chance, dass Entwickler sie sehen.

Ich vermeide jedoch die Duplizierung von Kommentaren zwischen Header- und Quelldateien (es fühlt sich einfach wie eine Verschwendung an). Es ist wirklich ärgerlich, wenn Sie Vim verwenden, aber die meisten IDEs nehmen die Kommentare der Header-Datei auf und fügen sie in Dinge wie Intellisense oder Parameterhilfe ein.

[1] Ausnahmen von dieser Regel sind generierte Header-Dateien aus bestimmten COM-Bibliotheken.

Dies hängt oft davon ab, was als Codierungsstandard festgelegt ist. Viele Leute ziehen es vor, die Dokumentation in der .h-Datei abzulegen und die Implementierung in der .c-Datei zu belassen. Viele IDEs mit Codevervollständigung werden dies auch leichter erkennen als die Dokumentation in der .c-Datei.

Aber ich denke, der Hauptpunkt beim Einfügen der Dokumentation in die .h-Datei betrifft das Schreiben einer Bibliothek oder Assembly, die mit einem anderen Programm geteilt wird. Stellen Sie sich vor, dass Sie eine .dll (oder .so) schreiben, die eine Komponente enthält, die Sie verteilen werden. Andere Programmierer fügen Ihre .h-Datei hinzu, aber sie haben (oder brauchen) oft nicht die Implementierungsdatei dahinter. In diesem Fall ist die Dokumentation in der .h-Datei von unschätzbarem Wert.

Dasselbe gilt, wenn Sie eine Klasse zur Verwendung in demselben Programm schreiben. Wenn Sie mit anderen Programmierern zusammenarbeiten, sehen sich diese Programmierer meistens nur die Header-Datei an, um zu erfahren, wie Sie mit Ihrem Code interagieren, und nicht, wie der Code implementiert wird. Wie es implementiert wird, ist nicht Sache der Person oder des Codes, der die Komponente verwendet. Auch hier hilft die Dokumentation im Header dieser Person oder diesen Personen dabei, herauszufinden, wie dieser Code verwendet wird.

Bedenken Sie, dass es möglich ist, diese Funktionen zu verwenden, während sie nur die Header und eine kompilierte Version der Implementierung haben. Stellen Sie sicher, dass alles, was für die Verwendung Ihrer Funktionen erforderlich ist, in der Kopfzeile dokumentiert ist. Implementierungsdetails können in der Quelle dokumentiert werden.

Die Kommentare im Header gegenüber der Implementierungsdatei sollten den Unterschied in der Verwendung der beiden widerspiegeln.

Wenn Sie eine Schnittstellendokumentation erstellen (z. B. zum Extrahieren mit Doxygen, in derselben allgemeinen Reihenfolge wie JavaDocs), gehört das eindeutig in den Header. Auch wenn Sie die Kommentare nicht extrahieren, um eine separate Dokumentation zu erstellen, gilt die gleiche allgemeine Idee – Kommentare, die die Schnittstelle erklären/wie der Code verwendet wird, gehören hauptsächlich oder ausschließlich in den Header.

Kommentare in der Implementierung sollten sich generell auf die Implementierung beziehen. Entgegen der häufigen Praxis, anstatt zu versuchen, zu erklären wie Dinge funktionieren, sollten die meisten erklären warum besondere Entscheidungen getroffen wurden. Dies gilt insbesondere, wenn Sie Entscheidungen treffen, die sinnvoll sind, aber möglicherweise nicht offensichtlich sind (z. B. feststellen, dass Sie dies getan haben nicht verwenden Sie einen Quicksort, da Sie eine stabile Sortierung benötigen).