Naming Include Guards

Question

How are C++ include guards typically named? I tend to see this a lot:

#ifndef FOO_H
#define FOO_H

// ...

#endif

However, I don't think that's very intuitive. Without seeing the file name it's difficult to tell what FOO_H is there for and what its name refers to.

What's considered best practice?

While the name may be more or less intuitive, the fact is that with a little experience you stop reading those lines. The eyes and the brains get used to `#ifdef blahblah...` and I hardly ever actually read what is being check, it is a include guard. — David Rodríguez - dribeas, Feb 01 '11 at 20:43
A somewhat useful viewpoint on this: http://stackoverflow.com/questions/1744144/adding-an-include-guard-breaks-the-build/1744302#1744302 — Fred Nurk, Feb 01 '11 at 20:48
Anyone doing C++ development had better get used to recognizing header guards very quickly. It will ALWAYS follow the standard you're seeing. "Best" practice (in quotes because it's required) is to put the ifndef first, the define immediately after, and finish it at the end of the file. I suggest you learn to recognize this asap. — Edward Strange, Feb 01 '11 at 20:50

score 29 · Answer 1 · answered Feb 02 '11 at 07:53

I personally follow Boost's recommendation. It's perhaps one of the largest collection of C++ libraries of good quality around and they don't have problem.

It goes like:

<project>_<path_part1>_..._<path_partN>_<file>_<extension>_INCLUDED

// include/pet/project/file.hpp
#ifndef PET_PROJECT_FILE_HPP_INCLUDED

which is:

legal (note that beginning by _[A-Z] or containing __ is not)
easy to generate
guaranteed to be unique (as a include guard) within a project (else you have two files at the same place)
guaranteed not to be used for anything else (if you end another macro with INCLUDED you're spoiling for a fight)

I've read about GUID but those look weird.

And obviously I'd rather than all compilers implement #pragma once (or better, #pragma multiple and "once" be the default behavior...)

Personally, I feel that adding the extension is redundant, but I like the way _INCLUDED actually says what it stands for, +1 for that. My preference is to use INCLUDE_GUARD_FOO (without the redundant _H, we only ever need include guards for headers, after all) which is even a bit more to the point imho, but that's a matter of taste, really. — cmaster - reinstate monica, Jun 25 '13 at 21:32
@cmaster The addition of the _H can be helpful in situations where you have a C and a C++ implementation of some functionality (using a .h and a .hpp file, respectively). — Squirrel, Jan 13 '18 at 05:47

score 23 · Accepted Answer · answered Feb 01 '11 at 20:28

23

From my own experience, the convention is to name the inclusion guards after the header file containing them with the exception that the name is all in caps and the period is replaced with an underscore.

So test.h becomes TEST_H.

Real life examples of this include Qt Creator, which follows this convention when auto-generating class header files.

answered Feb 01 '11 at 20:28

Nathan Osman

71,149
71
256
361

5

It's good to just use FILENAME_H as the include guard name because you keep all files for all projects and all libraries in the same directory with no subdirectories anyway, so you know they never have conflicting file names... – Fred Nurk Feb 01 '11 at 20:57
2

While this is common practice, it might not be good enough, depending on what else your shop does with #defines and other names. – John Dibling Feb 01 '11 at 20:58

score 16 · Answer 3 · edited Jun 19 '18 at 15:48

16

Taken directly from google's style guide:

All header files should have #define guards to prevent multiple inclusion. The format of the symbol name should be <PROJECT>_<PATH>_<FILE>_H_. To guarantee uniqueness, they should be based on the full path in a project's source tree. For example, the file foo/src/bar/baz.h in project foo should have the following guard:
 #ifndef FOO_BAR_BAZ_H_
 #define FOO_BAR_BAZ_H_
 ...
 #endif  // FOO_BAR_BAZ_H_

I use this style in my own projects.

edited Jun 19 '18 at 15:48

RJ7

883
9
17

answered Feb 01 '11 at 20:34

Marlon

19,924
12
70
101

5

Although generally speaking the google coding standard is one of the worse I've ever seen, I do prefix with namespace. It's absolutely necessary if you've got anything with the same names in multiple namespaces. – Edward Strange Feb 01 '11 at 20:48
I've been trying to figure out, is there any reasoning behind the trailing underscore? – Toby May 11 '16 at 08:31
2

@Toby Just to make it (more) unique... If someone has a `CONFIG_H` already (like an included library e.g.) then using `CONFIG_H_` won't clash with it. Same reason some folks use a leading underscore, but they shouldn't because thags reserved. – RastaJedi Aug 10 '16 at 00:16
3

Link is dead, updated to [https://google.github.io/styleguide/cppguide.html](https://google.github.io/styleguide/cppguide.html) now. – SedriX Aug 10 '17 at 01:18
I believe, this is a more clearer way to protect a header, because a comment as a header name (after the `#endif` directive) allows to distinguish it from other constants. – Kassi May 26 '20 at 16:12

score 5 · Answer 4 · answered Feb 01 '11 at 23:00

Look at the code that #include's your header.

If it is something like:

#include "mylib/myheader.h"

mylib/myheader.h is already a unique name. Just capitalize and replace / and . with _

#define MYLIB_MYHEADER_H

If you have two headers on your include path with the same name relative to the include path, you already have a collision at that level.

score 4 · Answer 5 · answered Feb 01 '11 at 20:27

4

Replace FOO_H with FOO_H_INCLUDED and it's clearer.

answered Feb 01 '11 at 20:27

John

15,990
10
70
110

score 2 · Answer 6 · answered Feb 01 '11 at 20:48

2

I usually look what time it is and just append that to the end of it, i.e. FOO_H_248, it's an extra precaution, and you'll never have to remember it anyway, so you don't need to worry about the fact that it's cryptic.

answered Feb 01 '11 at 20:48

Benjamin Lindley

101,917
9
204
274

Do you use the 12 or 24 hour clock and is this local time? ;-) – T33C Feb 01 '11 at 20:54
8

@T33C: 12? 24? What are you talking about? It's just a regular 17 hour clock. And it's local time to wherever the Pope is at that moment. – Benjamin Lindley Feb 01 '11 at 20:58

score 2 · Answer 7 · edited Jul 08 '14 at 03:33

As others mentioned before, a very common convention is to use the uppercase version of the name, and the dot replaced by an underscore: foo.h -> FOO_H

However, this can lead to name collisions with simple and/or common names. For this reason, autogenerated header like the stdafx.h in non-empty Visual C C++ projects append some random string, like:

#ifndef FOO_H__NsknZfLkajnTFBpHIhKS
#define FOO_H__NsknZfLkajnTFBpHIhKS
#endif

http://www.random.org/strings/ is a useful random generator for this.

Also, if the file is part of some submodule, or its contents reside in one specific namespace, I tend to add that to the guard too:

#ifndef SOMECOMPONENT_FOO_H__NsknZfLkajnTFBpHIhKS
#define SOMECOMPONENT_FOO_H__NsknZfLkajnTFBpHIhKS

namespace somecomponent
{
  ...
}

#endif

These are reserved names, because of the double underscore. So it is NOT good practice to use that. — Ben Voigt, Nov 02 '14 at 16:57

score 1 · Answer 8 · answered Feb 01 '11 at 20:27

1

I normally use something like FOO_H_INCLUDED_. A few (Microsoft) headers have what looks a lot like a string representation of a GUID, but I've never needed anything quite that elaborate.

answered Feb 01 '11 at 20:27

Jerry Coffin

476,176
80
629
1,111

score 1 · Answer 9 · answered Feb 01 '11 at 20:28

Usually people do that by file name so that each file's code only gets compiled and added once. You could make FOO_H whatever you want, but almost everything I've ever coded or seen has used the file name. Just make sure it's unique because you don't want your FOO_H conflicting with someone else's FOO_H.

Naming Include Guards

9 Answers9

Linked