Header Guards

A header guard is a piece of code that goes at the top and bottom of a header file that prevents the file from being linked more than once at compile time. A header file can be included from many different c files. The guard only lets the first inclusion of the header file actually parse. This prevents all the coding errors you would receive if the same code was written twice such as multiple definition errors and variable over writing. Examples follow…

The “#ifndef” Way

Note that,

“In a user header file, the macro name should not begin with ‘_’.” – GNU GCC: The C Preprocessor

Also, it is standard for system header files guard identifiers to begin with __ (e.g. #ifndef __IDENTIFIER_H). You should not do that either! This is because macros beginning with “_<capital letter>” or “__” are part of a reserved namespace for system macros.

[code lang=”c”]

// Top of header file…
#ifndef <IDENTIFIER>_H
#define <IDENTIFIER>_H

// Rest of header code…

#endif // #ifndef <IDENTIFIER>_H
// EOF

[/code]

The indentifier just has to be some unique word that won’t be used as an identifier for another header guard. Usually the filename without the extension is used as the indentifier, for example, if the file controlled the flashing of led’s, you could use

[code lang=”c”]

#ifndef LEDS_H
#define LEDS_H

// Codey code code…

#endif // #ifndef LEDS_H

// EOF
[/code]

This syntax is the same as what you would use to include pieces of code in a shared module that are specific to your application. This is against the ‘modular’ principle, but sometimes it needs to be done.

The “#pragma once” Way

The other way to create a header guard is to use the #pragma once directive. This approach has been supported by most compilers for a smaller length of time the #ifndef method, but in todays you can be confident that most compilers support it (including GCC).

This method in some cases allows faster compilation and greater optimisation, due to the compiler being able to determine weather to include code before the pre-processor is run. It also is simpler to write, and does not require any termination code at the end of file as does the #ifndef method.

However, it is not supported by all preprocessors, so is not as portable as the #ifndef way.

[code lang=”c”]

// Top of header file

// Header guard
#pragma once

// Codey code code

// EOF

[/code]

The #import Method

The third and final way is to use the #import directive instead of #include. However, this is only considered standard in Objective-C, and is deprecated in both C and C++.

Problems arise because the user must know that the header must be only included once, and use the #import directive rather than #include.

[code lang=”c”]
// A C file

// This header file will only be imported once
#import "abc.h"

// However, problems will arise if the user accidently writes instead
#include "abc.h"

// EOF
[/code]