Using inclusion guards

One of the things that struck me as really odd, ever since I first started learning C++, was the fact that it wasn't (and still isn't) allowed to include the same header file more than once. Luckily though, there is a very easy solution for this, which I'd like to show you today.

First allow me to explain the problem with a little example: suppose we're writing some code to represent a small pet-shop. You might encounter a few files as follows:

File "animal.h"

struct animal
{
  int age;
};

File "dog.h"

#include "animal.h"

File "cat.h"

#include "animal.h"

File "shop.cpp"

#include "cat.h"
#include "dog.h"

"Dog" needs to include the "animal" header, as does "cat" - they are both animals after all. Our shop sells both animals, so we include them both in our "shop". Easy enough, at first sight - but there is a catch: you've just included "animal.h" twice in your shop!

You see, each include statement in C++ is literally replaced with the entire header file, which means a double inclusion of the same header (animal.h) in the example above. Naturally, this would result in errors, so this is simply not allowed. Other languages, such as Delphi and Java, do allow this, but they handle their includes (or uses and imports respectively) a bit differently.

There are two easy solutions available to overcome this problem: both have their merits and drawbacks.

1. The preprocessor directive #pragma once

   
   

   This one is the easiest - simply include #pragma once as the first line in your header file. This statement is a preprocessor directive, which basically tells the compiler to only include this header once.

   There is a catch, though: pragma directives are not supported by every compiler out there, making your code compiler-specific.

2. Inclusion guards

   
   

   By defining a globally unique identifier, we can ensure that a piece of code is included only once. The following piece of code shows you how to do this:

   #ifndef ANIMAL_H
   #define ANIMAL_H
   ...
   #endif

   
   

It's very easy to add this to your code, and it works on each and every C++ compiler. Alas, there are a few problems you should be aware of.

First of all, you need to make sure that the identifier you define is unique across your entire project. Second, it's a bit more error-prone than the pragma statement (you need to include both the define and the check around your code).

Personally, I've come to accept the inclusion guard as default for my projects. It's easy enough to use a global identifier (use the name of your header file), and type the inclusion guards as early as possible in your header, so you won't forget them. In case of user error, the compiler will most likely raise an error and slap you on your wrist.

In the end, it all comes down to developer preference: choose whichever you like - but please be sure to choose one of them. It'll make your life a lot easier...