What is the recommended naming convention for include guards?

Question

How are 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?

Heckle

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. – Versieversification

A somewhat useful viewpoint on this: #1744644 – Rafat

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. – Dada

Answer 1

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.

Vogeley

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... – Rafat

While this is common practice, it might not be good enough, depending on what else your shop does with #defines and other names. – Extragalactic

Answer 2

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...)

Nerin

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. – Mackoff

@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). – Laynelayney

Answer 3

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.

Juback

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. – Dada

I've been trying to figure out, is there any reasoning behind the trailing underscore? – Haman

@Haman 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. – Viscus

Link is dead, updated to https://google.github.io/styleguide/cppguide.html now. – Plascencia

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. – Holiness

Answer 4

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.

Pironi

Answer 5

Replace FOO_H with FOO_H_INCLUDED and it's clearer.

Negligee

Answer 6

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.

Davon

Do you use the 12 or 24 hour clock and is this local time? ;-) – Wien

@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. – Davon

Answer 7

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

Jecoa

These are reserved names, because of the double underscore. So it is NOT good practice to use that. – Sutherland

Answer 8

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.

Bravar

Answer 9

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.

Baugher