Schreiben Sie Kommentare in der Quelle oder Header-Datei

Question

Dies ist eine sehr einfache Frage, die ich bin überrascht, ich habe nirgendwo sonst auf SO gefunden. Ich frage mich, welche Kommentare sollten oder nicht in Header/Quelldateien sein. Das wäre redundant oder erforderlich, wenn es sowohl in der Kopfzeile als auch in der Quelle deklariert wird. Bisher habe ich es so tun:

main.c oder main.cpp

int main() 
{ 
    // Comments to describe what happens in main 
} 

foo.h

// Comments for documentation and which gives information about the function itself 

/** 
* \fn void aFunction(void) 
* \brief This function is a function 
*/ 
void aFunction(void); 

foo.c oder foo.cpp

void aFunction(void) 
{ 
    // Comments to describe and explain what happens within this function 
} 

• Nicht viel Kommentare in main, im Grunde nur die beschreiben, welche Funktionen aufgerufen werden und warum
• In Header nur Kommentare die Funktion selbst beschreiben; Parameter, kurze, Rückkehr etc.
• In der Quelle, nur Kommentare zu beschreiben was innerhalb der Funktion passiert; Schleifen, Zustand etc.

Das ist, was ich sicher weiß. Gibt es mehr Kommentare in Haupt-, Quell- oder Kopfzeile? Sollte ich die Kommentare hinzufügen ich in der Regel nur in der Quelle auch in der Kopfzeile setzen, wie folgt aus:

foo.c oder foo.cpp

/** 
* \fn void aFunction(void) 
* \brief This function is a function 
*/ 
void aFunction(void) 
{ 
    // Comments to describe and explain what happens within this function 
} 

Ich weiß, diese Art von subjektiv ist, sondern auch Ich denke, das Kommentieren ist eine Kunst und die Kunst, die dennoch subjektiv ist, muss technisch sein.

Answer 1

C-Dateien sollten die üblichen Kommentare enthalten, die Sie schreiben, wenn Sie Code schreiben. Was macht es und warum? Normalerweise am Ende jeder Zeile, es sei denn, es sind umfangreichere Kommentare erforderlich.

H-Dateien können entweder ein kurzes Minimum enthalten und erklären, was eine Funktion als Parameter nimmt und was sie zurückgibt. Oder alternativ könnte es eine vollständige Dokumentation enthalten, wie die Funktion verwendet werden sollte. Wenn die vollständige Dokumentation nicht in der Header-Datei bereitgestellt wird, müssen Sie sie separat schreiben. Hinweis: ein paar Zeilen Doxygen-Mist, nur um eine Art nutzloser "Dokumentations" -Datei zu generieren, zählen nicht als vollständige Dokumentation.

H-Dateien dokumentieren, was eine Funktion macht und wie sie verwendet werden sollte, ohne Implementierungsdetails zu erwähnen. Es ist wichtig zu erkennen, dass eine h-Datei die vollständige, eigenständige Schnittstelle für die entsprechende c-Datei (oder Bibliothek) sein sollte. Alle Typen und Abhängigkeiten, die der Aufrufer beachten muss, sollten in der h-Datei vorhanden sein.

Dies beinhaltet alle Vor- und Nachbedingungen: Was muss vor dem Aufruf einer Funktion ausgeführt werden? Welche Ressourcen hat die Funktion verwendet? Hat es irgendwelche Handles/Dateien/Ressourcen geöffnet, die später aufgeräumt werden müssen? Hat es irgendeinen globalen Staat verändert? Usw.

Die entsprechenden c-Datei (en) werden dem Benutzer nicht unbedingt zur Verfügung gestellt, noch sollte der Benutzer die c-Datei lesen müssen, um zu verstehen, wie die dort verwendeten Funktionen zu verstehen sind. Alles sollte aus der h-Datei allein ersichtlich sein.

Answer 2

Persönlich ist meine Faustregel, einfach Kommentare zu vermeiden, wenn überhaupt möglich.

Um dies zu tun, so viel wie möglich;

Machen Sie Deklarationen in Headern, die selbstdokumentieren, durch geeignete Wahl von Typnamen, Konstanten, Aufzählungswerten, Funktionsnamen, Variablennamen usw .;

Machen Sie Funktionsdefinitionen so klein und einfach wie möglich, um es so klar wie möglich zu machen, wie sie ihre Sache machen. Machen Sie die Funktionen so selbst-dokumentarisch wie möglich, indem Sie Variablennamen, lokale Typen usw. auswählen. Unterteilen Sie große Funktionen in eine Menge kleinerer Funktionen und machen Sie ALLE Funktionen so selbsterklärend wie möglich.

Wählen Sie Dateinamen (für Header und Kompilierungseinheiten), so dass Gruppierungen von Funktionen und Deklarationen offensichtlich sind.

Verwenden Sie dann Kommentare nur, wenn sie benötigt werden, um etwas zu erklären, das nicht offensichtlich ist, indem Sie den Code selbst betrachten. Zum Beispiel ist es besser zu erklären, WARUM Code etwas tut und das WIE durch den Code selbst beschrieben werden kann. Wenn eine Funktion bestimmte Vorbedingungen (Dinge, die beim Aufruf als wahr angenommen werden) oder Post-Bedingungen (Dinge, die die Funktion garantiert, wenn sie zurückkehrt, wenn die Vorbedingungen erfüllt sind) garantiert, können diese in Kommentaren beschrieben werden.

Ich verwende keine Kommentare für Dinge wie die Versionsgeschichte verfolgen (das ist, was Versionskontrollsysteme sind).

Manchmal ist es unmöglich, Code so zu schreiben, dass er einfach und offensichtlich ist. In diesen Fällen sind Kommentare erforderlich. Aber die Probleme mit Kommentaren (z. B. vergessen, sie zu aktualisieren, so dass sie nicht mehr mit dem Code übereinstimmen) sind so bedeutend, dass es besser ist, hart zu arbeiten, damit sich der Code - ohne Kommentare - so gut wie möglich beschreibt.

Dies bedeutet auch, hart arbeiten, um kryptischen Code zu vermeiden. Schreibe keine Aussagen mit 25 Nebenwirkungen. Code einrücken, damit er mit der tatsächlichen Struktur übereinstimmt (Code-Formatierer können dabei helfen). Vermeide Makros (da sie Dinge tun können, die mit dem Umfang inkonsistent sind) so weit wie möglich.