When a translation unit contains a complex hierarchy of nested header files, it is possible for a particular header file to be included more than once. This can be, at best, a source of confusion. If this multiple inclusion leads to multiple or conflicting definitions, then this can result in undefined or erroneous behaviour.

Example

/* file.h */ 
#ifndef FILE_H 
/* Non-compliant - does not #define FILE_H */ 
#endif

In order to facilitate checking, the contents of the header should be protected from being included more than once using one of the following two forms:

<start-of-file> 
#if !defined ( identifier ) 
#define identifier
  /* Contents of file */ 
#endif 
<end-of-file>

<start-of-file> 
#ifndef identifier 
#define identifier
  /* Contents of file */ 
#endif 
<end-of-file>

Note: the identifier used to test and record whether a given header file has already been included shall be unique across all header files in the project.

Note: comments are permitted anywhere within these forms.

MISRA-C 2004 Rule 19.15 (required): Precautions shall be taken in order to prevent the contents of a header file being included twice.

Include guard is not provided.

When a translation unit contains a complex hierarchy of nested header files it can happen that a particular header file is included more than once. This can be, at best, a source of confusion. If it leads to multiple or conflicting definitions, the result can be undefined or erroneous behaviour.

Multiple inclusions of a header file can sometimes be avoided by careful design. If this is not possible, a mechanism must be in place to prevent the file contents from being included more than once. A common approach is to associate a macro with each file; the macro is defined when the file is included for the first time and used subsequently when the file is included again to exclude the contents of the file.

For example a file called "ahdr.h" might be structured as follows:

#ifndef AHDR_H
#define AHDR_H

/* The following lines will be excluded by the
   preprocessor if the file is included more
   than once */
...
#endif

Alternatively, the following may be used:

#ifdef AHDR_H
#error Header file is already included
#else
#define AHDR_H

/* The following lines will be excluded by the
   preprocessor if the file is included more
   than once */
...
#endif

MISRA-C++ 2008 Rule 16-2-3 (required): Include guards shall be provided.

The include guard shall use one of the following two forms:

<start-of-file>
// Comments allowed here
#if !defined ( identifier )
#define identifier
   // Contents of file
#endif
<end-of-file>
<start-of-file>
// Comments allowed here
#ifndef identifier
#define identifier
   // Contents of file
#endif
<end-of-file>

Rationale

These forms are mandated to facilitate checking.

Example

// file.h
#ifndef FILE_H

#endif

// file.cc
#include "file.h"
#define FILE_H    // Non-compliant