73

So I recently had a discussion where I work, in which I was questioning the use of a double include guard over a single guard. What I mean by double guard is as follows:

Header file, "header_a.hpp":

#ifndef __HEADER_A_HPP__
#define __HEADER_A_HPP__
...
...
#endif

When including the header file anywhere, either in a header or source file:

#ifndef __HEADER_A_HPP__
#include "header_a.hpp"
#endif

Now I understand that the use of the guard in header files is to prevent multiple inclusion of an already defined header file, it's common and well documented. If the macro is already defined, the entire header file is seen as 'blank' by the compiler and the double inclusion is prevented. Simple enough.

The issue I don't understand is using #ifndef __HEADER_A_HPP__ and #endif around the #include "header_a.hpp". I'm told by the coworker that this adds a second layer of protection to inclusions but I fail to see how that second layer is even useful if the first layer absolutely does the job (or does it?).

The only benefit I can come up with is that it outright stops the linker from bothering to find the file. Is this meant to improve compilation time (which was not mentioned as a benefit), or is there something else at work here that I am not seeing?

21
  • 36
    This just adds another layer of brittleness to the code. A second layer is completely unnecessary.
    – DeiDei
    Jun 19, 2017 at 11:20
  • 19
    Not the linker, but the pre-processor. Honestly, any such benefit seems negligible to me on a modern build system, if you only include what you need. His "explanation" is more reminiscent of an expert beginner to be honest. Jun 19, 2017 at 11:20
  • 18
    One upon a time, there might have been one or two compilers stupid enough to open the file each time to check the include guard. No compiler produced in this millennium would do that, as it can just keep a table of files and include guards and consult that before opening the file.
    – Bo Persson
    Jun 19, 2017 at 11:40
  • 7
    It's completely unnecessary. There is no benefit at all. Jun 19, 2017 at 11:51
  • 34
    Note that names that contain two consecutive underscores (__HEADER_A_HPP__) and names that begin with an underscore followed by a capital letter are reserved for use by the implementation. Don't use them in your code. Jun 19, 2017 at 12:20

5 Answers 5

107

I am pretty sure that it is a bad practice to add another include guard like:

#ifndef __HEADER_A_HPP__
#include "header_a.hpp"
#endif

Here are some reasons why:

  1. To avoid double inclusion it is enough to add a usual include guard inside the header file itself. It does the job well. Another include guard in the place of inclusion just messes the code and reduces readability.

  2. It adds unnecessary dependencies. If you change include guard inside the header file you have to change it in all places where the header is included.

  3. It is definitely not the most expensive operation comparing the whole compilation/linkage process so it can hardly reduce the total build time.

  4. Any compiler worth anything already optimizes file-wide include-guards.

2
  • 2
    If you change include guard inside the header file you have to change it in all places where the header is included. .... well, technically, no you don't, but I think that kind of proves the point even further.
    – txtechhelp
    Jun 21, 2017 at 7:27
  • I have seen people do this when trying to get around some issues with Oracle Pro-C pre-processor. Still don't like it. Jun 21, 2017 at 9:58
51

The reason for putting include guards in the header file is to prevent the contents of the header from being pulled into a translation unit more than once. That's normal, long-established practice.

The reason for putting redundant include guards in a source file is to avoid having to open the header file that's being included, and back in the olden days that could significantly speed up compilation. These days, opening a file is much faster than it used to be; further, compilers are pretty smart about remembering which files they've already seen, and they understand the include guard idiom, so can figure out on their own that they don't need to open the file again. That's a bit of hand-waving, but the bottom line is that this extra layer isn't needed any more.

EDIT: another factor here is that compiling C++ is far more complicated than compiling C, so it takes far longer, making the time spent opening include files a smaller, less significant part of the time it takes to compile a translation unit.

5
  • 7
    Here's a link to back up your "hand-waving" with some documentation ;-) : gcc.gnu.org/onlinedocs/cppinternals/Guard-Macros.html
    – Arne Vogel
    Jun 19, 2017 at 13:13
  • @ArneVogel I noticed the docs say: "There must be no tokens outside the controlling #if-#endif pair, but whitespace and comments are permitted." Does 'tokens' include #pragma once?
    – sh3rifme
    Jun 19, 2017 at 14:43
  • 3
    @sh3rifme Yes. Read that sentence as "The only things you can put outside the controlling #if-#endif pair without disabling the optimization are whitespace and comments." But you shouldn't be using #pragma once anyway.
    – zwol
    Jun 19, 2017 at 15:34
  • well, you could put #pragma once inside the #ifndef/#endif block. However we don't use #pragma once because one of the compilers we use at work doesn't support it.
    – Tom Tanner
    Jun 21, 2017 at 8:30
  • @sh3rifme: #pragma once is not a token but a preprocessor directive. These are also not allowed for the optimization to work, though. However, GCC supports #pragma once, so the optimization and #pragma once are redundant. As Tom Tanner suggested, if you use both #pragma once and include guards, you might as well put the pragma inside the #ifndef/#endif block. In the unlikely case your compiler has the multiple includes optimization but does not support #pragma once, this should have you covered. That said, #include-behavior is notoriously implementation-dependent anyway.
    – Arne Vogel
    Jun 21, 2017 at 11:47
22

The only benefit I can come up with is that it outright stops the linker from bothering to find the file.

The linker will not be affected in any way.

It could prevent the pre-processor from bothering to find the file, but if the guard is defined, that means that it has already found the file. I suspect that if the pre-process time is reduced at all, the effect would be quite minimal except in the most pathologically recursively included monstrosity.

It has a downside that if the guard is ever changed (for example due to conflict with another guard), all the conditionals before the include directives must be changed in order for them to work. And if something else uses the previous guard, then the conditionals must be changed for the include directive itself to work correctly.

P.S. __HEADER_A_HPP__ is a symbol that is reserved to the implementation, so it is not something that you may define. Use another name for the guard.

3
  • Apologies for the confusion with the linker/pre-processor. You say that __HEADER_A_HPP__ is reserved to the implementation, what do you mean by this? Is it specifically using those semantics that's the issue, like math.hpp and __MATH_HPP__?
    – sh3rifme
    Jun 19, 2017 at 11:48
  • 13
    @sh3rifme the standard says that all identifiers that contain two consecutive underscores are reserved to the implementation. There are other reserved identifiers as well. I recommend acquainting yourself with those rules.
    – eerorika
    Jun 19, 2017 at 11:55
  • 7
    @sh3rifme: Reserved to the implementation, which may include such usages as automatically defining __HEADER_A_HPP__ when you include header_a.hpp. This of course breaks your header guard, which assumes it's defined only on the second line.
    – MSalters
    Jun 19, 2017 at 12:43
17

Older compilers on more traditional (mainframe) platforms (we're talking mid-2000s here) did not used to have the optimisation described in other answers, and so it really did used to significantly slow down preprocessing time having to re-read header files that have already been included (bearing in mind in a big, monolithic, enterprise-y project you're going to be including a LOT of header files). As an example, I've seen data that indicates a 26-fold speedup for a file with 256 header files each including the same 256 header files on the VisualAge C++ 6 for AIX compiler (which dates from the mid-2000s). This is a rather extreme example but this sort of speed-up does add up.

However, all modern compilers, even on mainframe platforms such as AIX and Solaris, perform enough optimisation for header inclusion that the difference these days really is negligible. Therefore there is no good reason to have these any more.

This does, however, explain why some companies still hang on to the practice, because relatively recently (at least in C/C++ codebase age terms) it was still worthwhile for very large monolithic projects.

3
  • I remember having to use an IBM fortran compiler once, and it made snails looks like racing horses. One file took no less than half an hour to compile on quite potent hardware. gfortran did the same job within a fraction of that time. So, maybe IBM compilers are not the best reference for measuring compilation speed. Anyway, on a modern kernel, those 256 header files will still be in the page cache when the compiler attempts to read them, so the 64k opens on the same 256 files should take no more than a second if a syscall is less than 10 microseconds. Jun 19, 2017 at 21:25
  • 1
    @cmaster not only the opening but the reading - remember the preprocessor has to scan to the last #endif
    – Muzer
    Jun 20, 2017 at 8:32
  • 2
    Which also is still in the page cache. Even if each of the 256 files is 128 kiB in size, that's just 32 MiB of data, totaling to 8 GiB of data that needs to be copied from kernel space to user space. Modern hardware can do that in less than a second. If a compiler takes painfully long on this operation, it's 100% the fault of the compiler. Jun 20, 2017 at 8:54
8

Although there are people arguing against it, in practice '#pragma once' works perfectly and the main compilers (gcc/g++, vc++) support it.

So whatever puristic argumentation people are spreading, it works a lot better:

  1. Fast
  2. No maintenance, no trouble with mysterious non-inclusion because you copied an old flag
  3. Single line with obvious meaning versus cryptic lines spread in file

So simply put:

#pragma once

at the start of the file, and that's it. Optimized, maintainable, and ready to go.

6
  • 1
    Include guards are not cryptic. Any C(++) programmer who knows what they're doing will immediately understand an include guard, and less experienced ones might even have to look up #pragma once (whereas they'd be fine with a standard include guard). Since all compilers will either optimize the include guard (real compilers) or fail to compile the #pragma once (toy compilers), it's not any faster than a standard include guard either.
    – Kevin
    Jun 21, 2017 at 3:40
  • 4
    @Kevin But main point is that guards are not error prone, and in 99.9% pragma once is enough which frees you from worrying about this good old know thing. In comparison to pragma once - they are truly cryptic and... slow. ;) Slow just because you need write them, maintain and read. Jun 21, 2017 at 7:50
  • 1
    @Kevin after 30+ years of using the #ifdef guards I was glad that my colleague Kris figured out that the 'new' pragma once was now supported everywhere. He wrote a script to bulk replace it and although it's just a small thing, this is the sort of thing that makes everybody happy. Thanks again Kris!
    – Bert Bril
    Jun 21, 2017 at 10:26
  • @tom can you name a few compilers that don't?
    – Bert Bril
    Jun 21, 2017 at 10:27
  • 1

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.