PRE06-A. Enclose header file in an inclusion sandwich

Until the early 1980s, large projects had a continual problem with the inclusion of headers. One group might have produced a graphics.h, for example, which started by including <stdio.h>. Another group might have produced keyboard.h, which also included <stdio.h>. And if <stdio.h> could not safely be included several times, arguments would break out about which header should include it. Sometimes an agreement was reached that each header should include no other headers, and therefore some application programs started with dozens of #include lines, and sometimes they got the ordering wrong or forgot a header that was needed.

Compliant Solution

All these complications disappeared with the discovery of a simple technique: each header should #define a symbol that means "I have already been included." Then the entire header should be enclosed in a "sandwich":

#ifndef HEADER_H
#define HEADER_H
/* // ... contents of the header */
#endif

Consequently, the first time that header.h is #include'd, all of its contents are included. If it should subsequently be #include'd again, its contents will be bypassed.

Risk Assessment

Using header names that conflict with the C standard library functions can result in not including the intended file.

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

[[Plum 85]] Rule 1-14
[[ISO/IEC 9899-1999]] Section 6.10, "Preprocessing directives," and Section 5.1.1, "Translation environment"