2

Are there any guidelines people tend to follow when selecting a name for their include guard? I don't understand why the name for the .h file will slightly differ from the name used in the include guard. For example, I have seen sphere.h and then #ifndef SPHERE_H_. Could I just as easily have used SPHERE_ or do the names have to match? Are the underscores also necessary?

Justin
  • 24,288
  • 12
  • 92
  • 142
prr
  • 33
  • 5
  • The argument over good names and possible collisions (what if you have two files with the same names in different directories that are part of the same project?) is part of the reason many people prefer `#pragma once`. Read more [here](https://stackoverflow.com/questions/1143936/pragma-once-vs-include-guards). – scohe001 May 15 '18 at 17:18
  • For `sphere.h`, I use `#ifndef GUARD_sphere_h`. – Eljay May 15 '18 at 17:20
  • 1
    At the least, don't use names containing double-underscores or names starting with an underscore and followed by an uppercase letter - both are reserved. –  May 15 '18 at 17:21
  • 1
    Underscores are not necessary, but do not use one at the beginning or two in a row anywhere. More on that in [What are the rules about using an underscore in a C++ identifier?](https://stackoverflow.com/questions/228783/what-are-the-rules-about-using-an-underscore-in-a-c-identifier) – user4581301 May 15 '18 at 17:21
  • 1
    This isn't known as an `#ifndef`, but as a *header guard* or *include guard* – Justin May 15 '18 at 17:22
  • 1
    I used to use a GUID, e.g. `H123e4567_e89b_12d3_a456_426655440000`. I had a little program to generate them in wholesale lots. Now I just use `#pragma once`. Voting to close as primarily opinion-based. – Jive Dadson May 15 '18 at 17:39
  • 1
    @JiveDadson — `#pragma once` can fail, and it’s not standard C++. – Pete Becker May 15 '18 at 17:52
  • @Pete Becker - There is only one major(ish) compiler that I know of which does not support #pragma once. It is not one that I need to worry about. – Jive Dadson May 15 '18 at 18:16

3 Answers3

6

To pick a good name for a header guard, consider these points:

1) the name has to be unique, so make it long and specific. That can usually be accomplished by including things like project name, module name, file name and file extension.

2) make sure you don't use names reserved for the implementation. So, names starting with underscore followed by a capital letter are out, as are names containing double underscore, names ending in _t and a few more.

3) make the name make sense to human readers. So don't just generate a UUID and use that.

4) convention dictates that you use all uppercase for macros to distinguish them from ordinary variables.

Underscores are not needed, as such, but since you cannot use spaces in macro names, underscores serve as a good alternative to keep things readable.

So, IMHO, a good guard name for a file foo.h in a submodule bar inside project baz is: BAZ_BAR_FOO_H .

Jesper Juhl
  • 30,449
  • 3
  • 47
  • 70
  • 1
    The main problem with GUID's is that they end up being Gnot-UIDs when somebody copies the header and modifies the C++ code without updating the GUID. That's not unusual when implementing sibling classes. – MSalters May 16 '18 at 11:16
  • 1
    @MSalters I did not recommend using GUIDs, quite the opposite. – Jesper Juhl May 16 '18 at 15:19
2

Most modern compiler support the #pragma once directive that could be used instead. See: https://en.wikipedia.org/wiki/Pragma_once

Paul Belanger
  • 2,354
  • 14
  • 23
1

The important thing about the symbols used for include guards is that they are unique. That means that not only do the include guards for every header file (including any library headers your project may be using) need to be unique, they must also not clash with any other symbols used anywhere in your project.

There are a couple common ways people go about ensuring uniqueness:

1) Use something like <PROJECT_NAME>_<FILE_NAME> (i.e. MYPROJECT_SPHERE_H)

Including your project name will help ensure your include guard doesn't clash with that of another "sphere.h" you include from some library. Using the file name and extension makes it easy to create include guards when adding a new header to your project and makes it very unlikely that name will be used anywhere else in the project (for a variable, function, etc.).

2) Use a UUID (i.e. GUARD_0be96322_7238_49d2_a967_e8fd9907cca1)

This is a very safe approach, since UUIDs are extremely unlikely to ever collide. It is harder to read though, and means you have to dig out your UUID generator whenever you create a new file.

Miles Budnek
  • 28,216
  • 2
  • 35
  • 52