#ifndef syntax for include guards in C++

Question

I'm currently studying for a CS course's final exam and I've run into a minor (maybe major?) issue regarding the syntax of C++ #ifndef.

I've looked at the syntax for #infndef when using it as an #include guard, and most on the web seem to say:

#ifndef HEADER_H
#define "header.h"
...
#endif

But my class's tutorial slides show examples as:

#ifndef __HEADER_H__
#define "header.h"
...
#endif

I was wondering what (if any) the difference was between the two. The exam will most likely ask me to write an #include guard, and I know conventional wisdom is to just go with what the prof / tutor says, but if there's a difference during compilation I'd like to know.

Estell

See here for a discussion of the rules your tutor is breaking, and here for an example what could go wrong if you break them. Also, include guards go inside the header. – Allowable

As it is, the inculded code makes no sense: you cannot #define a string literal. Did you mean #include "header.h" (the original wording) or #define HEADER_H (what usually goes inside a header preamble)? – Cookson

Answer 1

The usual practice is to do neither, and put the include guard inside the header file, as it reduces repetition. e.g.:

header.h

#ifndef HEADER_H
#define HEADER_H

// Rest of header file contents go here

#endif

Precisely what you use as the macro name is down to your particular coding standard. However, there are various subtle rules in the C and C++ standards that prevent you from using identifiers beginning with underscores,¹ so you should avoid __HEADER_H__, just to be on the safe side.

It's also worth mentioning that you should pick something that's unlikely to clash with anything else in your codebase. For example, if you happened to have a variable called HEADER_H elsewhere (unlikely, I realise), then you'd end up with some infuriating errors.

---

_{1. See e.g. section 7.1.3 of the C99 standard.}

Breadthways

...and if it isn't an implementation header file, it should avoid identifiers containing an underscore followed by another underscore or capital letter. – Barbette

@JerryCoffin: "containing", or "starting with"? – Breadthways

For C, starting. For C++, containing a doubled underscore is verboten as well (but underscore followed by cap is allowed as long as it's not at the beginning). – Barbette

@JerryCoffin: Interesting. Oh well, I think I'll stick with my summary in my answer of "various subtle rules". – Breadthways

"Each name that contains a double underscore _ _ or begins with an underscore followed by an uppercase letter (2.12) is reserved to the implementation for any use. Each name that begins with an underscore is reserved to the implementation for use as a name in the global namespace." §17.6.4.3.2 in n3290 C++ – Twentyfourmo

Answer 2

Names starting with a double underscore are reserved for the implementation, so I would advise against using __SOMETHING in your include guards. Also, try to chose names that make clashes unlikely. So it seems your class' tutorials are wrong on at least two counts. See this humorous article for example.

Caithness

Answer 3

An argument for putting the include guards in the file that includes the header, rather than in the header itself, is that if the file has already been included the compiler (specifically the preprocessor) doesn't have to open and read the include file again.

That's a weak argument. In practice, the time saved is trivial, and the potential for error is large.

In your example:

#ifndef HEADER_H
#include "header.h"
...
#endif

you don't show us the #define HEADER_H. Is it somewhere in header.h? If so, how do you know that the author of header.h chose to use HEADER_H as the name of the include guard macro? What if it changes to something else later?

If you decide to put the include guard in the including file, you should define the macro there as well:

#ifndef HEADER_H
#include "header.h"
#define HEADER_H
#endif

But, as other answers have already said, it's much better to put the guard in the header itself:

header.h :

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

and then the include simply has:

#include "header.h"

and has one less piece of information to worry about.

Invincible

Answer 4

I recommend #pragma once over #ifndef.

Ex:

#pragma once

// Rest of header file contents go here

Many compilers now support this (including GCC, LLVM/clang, and Microsoft), and it's easier to maintain, faster to compile, and less error-prone.

---

As I also state in my answer here, GCC's official documentation states: https://gcc.gnu.org/onlinedocs/cpp/Pragmas.html:

#pragma once

If #pragma once is seen when scanning a header file, that file will never be read again, no matter what. It is a less-portable alternative to using #ifndef to guard the contents of header files against multiple inclusions.

And Microsoft also strongly supports its use: https://learn.microsoft.com/en-us/cpp/preprocessor/once?view=msvc-170

once pragma

Specifies that the compiler includes the header file only once, when compiling a source code file.

...

The use of #pragma once can reduce build times, as the compiler won't open and read the file again after the first #include of the file in the translation unit. It's called the multiple-include optimization.

(emphasis added):

We recommend the #pragma once directive for new code because it doesn't pollute the global namespace with a preprocessor symbol. It requires less typing, it's less distracting, and it can't cause symbol collisions. Symbol collisions are errors caused when different header files use the same preprocessor symbol as the guard value. It isn't part of the C++ Standard, but it's implemented portably by several common compilers.

Heartland

Answer 5

There's no difference if you don't use underscore in variable names anywhere else, it's only a naming convention.

You just need to put something unique.

Polemist

Not true. Names beginning with two underscores are reserved for the implementation (in C99, at least). – Breadthways

+1: Actually answers OP's question instead of stating the "usual" way of doing things. – Adnah

It's not just a convention. Using an identifier starting with a __ makes your code's behavior undefined. The implementation (either the compiler or the standard library) is free to use the name __HEADER_H__ for its own purposes; if it does so, your own use of that identifier could mean literally anything. – Invincible

@trinithis: Using such identifiers puts you into the realm of undefined behaviour, although usually what that means in this case is that in certain situtaions, you'll end up with tricky-to-diagnose compile-time errors. – Breadthways

@OliCharlesworth I didn't know that, thank you. But basically you could put anything there and it will work too, right? – Polemist

@Marc: So long as you avoid the rules about names with underscores, then it doesn't really matter. Although obviously you should try to pick something that isn't likely to clash with anything else. – Breadthways

@Polemist since your answer is wrong, maybe you should add a note, to avoid confusion for future readers. – Caithness