CODEWITHSUNDEEP
c++c-preprocessorheader-files
foo
foo

Reputation: 291

C++ #ifndef for include files, why is all caps used for the header file?

I wonder why the name after the #ifndef directive is always all caps and don't seem to match the name of the actual header file? What are the rules surrounding this? I've been looking around the webs but, I haven't found any explanation for this. If my header file is called myheader.h would it then be ok to use:

#ifndef MYHEADER

If so, why? What are the rules?

Upvotes: 7

Views: 12981

Answers (7)

Component 10
Component 10

Reputation: 10497

It's completely subjective and there are no enforced rules other than those normally associated with the character set for naming pre-processor macros. It's conventional for macros to be defined in upper case. This tends to help them stand out in source code. A convention I tend to stick to is the strict capitalised version of the filename with the period replaced by an underscore and leading and trailing underscores. So, for a file called DataTableNameMangler.hpp the include guard would look like:

#ifndef _DATATABLENAMEMANGLER_HPP_
#define _DATATABLENAMEMANGLER_HPP_

...

#endif // _DATATABLENAMEMANGLER_HPP_

There's no great reason for this though I strongly recommend for consistency that the name matches the filename exactly. I normally use a little class creator script to generate my initial classes. The following Bash snippet gives an idea:

#!/bin/bash
INC_GUARD_NAME="_${1^^*}_HPP_"
echo "#ifndef $INC_GUARD_NAME"
echo "#ifndef $INC_GUARD_NAME"
echo
echo "class $1 {};"
echo
echo "#endif // $INC_GUARD_NAME"

Thus:

$ ./makeclass.bash DataTableNameMangler
#ifndef _DATATABLENAMEMANGLER_HPP_
#ifndef _DATATABLENAMEMANGLER_HPP_

class DataTableNameMangler {};

#endif // _DATATABLENAMEMANGLER_HPP_

This is naturally just a very basic example. Importantly, remember to put the comment before the guard name on the last line. #endif takes no parameters so the macro will be passed on to the C++ compiler which will complain about it if it's not commented.

Upvotes: 1

Holstebroe
Holstebroe

Reputation: 5133

The idea is to make sure your header file is only read once during build. The idiom to accomplish that is the structure:

   #ifndef _SOME_UNIQUE_NAME
   #define _SOME_UNIQUE_NAME
   /* The actual header code */
   #endif

This means that you should choose a name that you are pretty sure will be unique and is a valid identifier for #ifndef. You should also make sure that the identifier is not used in actual code or confused with a variable or something. Having an upper case tag marks the idiom clearly. Besides that, it is merely conventions not language that dictate that choice. Visual Studio's wizards generates a GUID like identifier for. Sone compilers support #pragma once that have the same effect.

Upvotes: 1

Matteo Italia
Matteo Italia

Reputation: 126867

There's no "rule", there are just conventions. The first and most used convention is that all precompiler macros are all uppercase, so header guards too should be all uppercase.

As for the macro name, what I use (and what most of the code I've seen uses) is just the name of the header (as said, turned to all uppercase) including extension, replacing the dot with an underscore, followed by _INCLUDED.

#ifndef MYHEADER_HPP_INCLUDED
#define MYHEADER_HPP_INCLUDED
// ...
#endif

Note that many prepend such identifiers with an underscore or a double underscore, but it's not good practice, since the standard specifies that identifiers beginning (or containing) double underscores and those beginning with a single underscore followed by an uppercase letter are reserved for compiler/library-specific stuff (e.g. __declspec in VC++ or macros used in the standard headers) at all scopes; all the other identifiers beginning with a single underscore are reserved at the global scope. So such identifiers shouldn't be used to avoid collisions.

More info on this stuff here.

Upvotes: 10

sbi
sbi

Reputation: 224129

Google for "include guard" to find what the thing is actually about.

About the all-caps: It's a convention for macros to be in all-upper-case. The reason is that macros are processed by the preprocessor, an arcane text processing tool, that knows nothing of C++, and is best shut out of common identifiers, lest it tramples all over them, creating a big mess.

Upvotes: 1

dgnorton
dgnorton

Reputation: 2247

It's not required to be all caps. It's just the common convention. I usually use something like #ifndef MYHEADER_H_INCLUDED.

Upvotes: 1

Vladimir
Vladimir

Reputation: 170859

You can use any name you want, but you want to make it unique so that value won't be defined outside your header by any chance, so using header name with uppercase is just a nice convention to ensure that.

Upvotes: 0

SLaks
SLaks

Reputation: 887777

These are preprocessor symbols and have no such rules. (as long as they match the #defines in the headers)

However, convention is to use all-caps for preprocessor symbols.

Upvotes: 13

Related Questions