Was soll und was soll nicht in einer Header-Datei sein? [geschlossen]

Welche Dinge sollten auf keinen Fall in einer Header-Datei enthalten sein?

Wenn ich zum Beispiel mit einem dokumentierten Industriestandardformat arbeite, das viele Konstanten enthält, ist es eine gute Praxis, diese in einer Headerdatei zu definieren (wenn ich einen Parser für dieses Format schreibe)?

Welche Funktionen sollen in die Header-Datei gehen?
Welche Funktionen sollten nicht?

Was in Überschriften zu setzen:

• Der minimale Satz von #includeAnweisungen, die erforderlich sind, um den Header kompilierbar zu machen, wenn der Header in einer Quelldatei enthalten ist.
• Präprozessorsymboldefinitionen von Dingen, die gemeinsam genutzt werden müssen und die nur über den Präprozessor ausgeführt werden können. Auch in C werden Präprozessorsymbole am besten auf ein Minimum beschränkt.
• Weiterleitende Deklarationen von Strukturen, die erforderlich sind, um die Strukturdefinitionen, Funktionsprototypen und globalen Variablendeklarationen im Hauptteil des Headers kompilierbar zu machen.
• Definitionen von Datenstrukturen und Aufzählungen, die von mehreren Quelldateien gemeinsam genutzt werden.
• Deklarationen für Funktionen und Variablen, deren Definitionen für den Linker sichtbar sind.
• Inline-Funktionsdefinitionen, aber Vorsicht hier.

Was nicht in einen Header gehört:

• Unentgeltliche #includeWeisungen. Diese unentgeltlichen Includes verursachen eine Neukompilierung von Dingen, die nicht neu kompiliert werden müssen, und können es manchmal so machen, dass ein System nicht kompiliert werden kann. Keine #includeDatei in einem Header, wenn der Header selbst diese andere Headerdatei nicht benötigt.
• Präprozessorsymbole, deren Absicht durch irgendeinen Mechanismus, irgendeinen anderen Mechanismus als den Präprozessor erreicht werden könnte.
• Viele, viele Strukturdefinitionen. Teilen Sie diese in separate Header auf.
• Inline-Definitionen von Funktionen, für die eine zusätzliche Funktion erforderlich #includeist, die geändert werden kann oder die zu groß sind. Diese Inline-Funktionen sollten wenig oder gar keinen Fan-Out haben, und wenn sie Fan-Out haben, sollten sie auf die im Header definierten Elemente lokalisiert werden.

Was macht die minimale Menge von #includeAussagen aus?

Dies stellt sich als nicht triviale Frage heraus. Eine TL; DR-Definition: Eine Header-Datei muss die Header-Dateien enthalten, die direkt jeden der direkt in der betreffenden Header-Datei verwendeten Typen definieren oder die direkt jede der in der betreffenden Header-Datei verwendeten Funktionen deklarieren, darf jedoch nichts anderes enthalten. Ein Zeiger- oder C ++ - Referenztyp gilt nicht als direkte Verwendung. Vorwärtsreferenzen werden bevorzugt.

Es gibt einen Platz für eine unbegründete #includeAnweisung, und dies erfolgt in einem automatisierten Test. Für jede Header-Datei in einem Softwarepaket erstelle und kompiliere ich automatisch Folgendes:

#include "path/to/random/header_under_test"
int main () { return 0; }

Die Kompilierung sollte sauber sein (dh frei von Warnungen oder Fehlern). Warnungen oder Fehler in Bezug auf unvollständige oder unbekannte Typen bedeuten, dass in der zu testenden Header-Datei einige #includeAnweisungen und / oder Vorwärtserklärungen fehlen. Gut zu beachten: Nur weil der Test bestanden wurde, bedeutet dies nicht, dass der #includeRichtliniensatz ausreicht, geschweige denn minimal.

Zusätzlich zu dem, was bereits gesagt wurde.

H-Dateien sollten immer enthalten:

• Quelltextdokumentation !!! Zumindest was ist der Zweck der verschiedenen Parameter und Rückgabewerte der Funktionen.
• Header Guards, #ifndef MYHEADER_H #def MYHEADER_H ... #endif

H-Dateien sollten niemals enthalten:

• Beliebige Form der Datenzuordnung.
• Funktionsdefinitionen. Inline-Funktionen können in einigen Fällen eine seltene Ausnahme sein.
• Alles beschriftet static.
• Typedefs, #defines oder Konstanten, die für den Rest der Anwendung keine Relevanz haben.

(Ich würde auch sagen, dass es nie einen Grund gibt, nicht konstante globale / externe Variablen zu verwenden, aber das ist eine Diskussion für einen anderen Beitrag.)

Ich würde wahrscheinlich nie nie sagen, aber Anweisungen, die Daten und Code generieren, während sie analysiert werden, sollten nicht in einer .h-Datei enthalten sein.

Makros, Inline-Funktionen und Vorlagen sehen möglicherweise wie Daten oder Code aus, generieren jedoch keinen Code, wenn sie analysiert werden, sondern wenn sie verwendet werden. Diese Elemente müssen häufig in mehr als einer .c- oder .cpp-Datei verwendet werden, sodass sie in die .h-Datei gehören.

Meiner Ansicht nach sollte eine Header-Datei die minimale praktische Schnittstelle zu einer entsprechenden .c- oder .cpp-Datei haben. Die Schnittstelle kann #defines, class, typedef, Strukturdefinitionen, Funktionsprototypen und weniger bevorzugte externe Definitionen für globale Variablen enthalten. Wenn eine Deklaration jedoch nur in einer Quelldatei verwendet wird, sollte sie wahrscheinlich aus der .h-Datei ausgeschlossen und stattdessen in der Quelldatei enthalten sein.

Einige mögen anderer Meinung sein, aber mein persönliches Kriterium für .h-Dateien ist, dass sie alle anderen .h-Dateien enthalten, die sie kompilieren müssen. In einigen Fällen kann dies eine Vielzahl von Dateien sein. Daher verfügen wir über einige effektive Methoden, um externe Abhängigkeiten wie Forward-Deklarationen für Klassen zu reduzieren, mit denen wir Zeiger auf Objekte einer Klasse verwenden können, ohne einen möglicherweise großen Baum von Include-Dateien einzuschließen.

Die Header-Datei sollte die folgende Organisation haben:

• Typ- und Konstantendefinitionen
• externe Objektdeklarationen
• externe Funktionsdeklarationen

Header-Dateien sollten niemals Objektdefinitionen, sondern nur Typdefinitionen und Objektdeklarationen enthalten.

Anweisungen, die beim Parsen Daten und Code generieren, sollten nicht in einer .hDatei enthalten sein. Aus meiner Sicht sollte eine Header-Datei nur die minimale praktische Schnittstelle zu einem entsprechenden .coder haben .cpp.