Best practices for use of C++ header files

Question

I have the following doubts on header files usage.

1 - Include guards placing after comments

/* Copyright Note and licence information (multiple lines) */
#ifndef FOO_H
#define FOO_H
// Header file contents
#endif

Herb Sutter says in his "C++ coding standards" book that code like the above is problematic. He is saying the "#ifndef" statements should appear in the first line of the header file. I haven't felt this as convincing. Is this followed by you guys/gals in header files?

2 - Using namespaces in header files

#ifndef FOO_H
#define FOO_H
namespace FooNameSpace{
    // Header file contents
}
#endif

Is the above code using correct practice? I mean, do you use namespaces in header files? I know why importing a namespace in header file is pointless but what about a declaration like the above?

If the above one is the correct method, how do you do "forward declaration" of a class which is in another namespace? Is it like

#ifndef FOO_H
#define FOO_H
namespace AnotherNameSpace{
    class AnotherFoo; // forward declaration
}

namespace FooNameSpace{
    // Use AnotherFoo here
}
#endif

The "forward declaration" is the only method to avoid "cyclic dependency", correct?

Answer 1

1. The order of the include guards and the comments is purely a matter of style - it won't have any measurable effect on speed of compilation.

2. Namespaces absolutely should be used in header files for declaring functions, classes, globals, etc. What you should not do is use using statements in header files -- it's impossible to unuse something in a source file that includes it, and you shouldn't force includers to add extra stuff to the global scope. If you need to use things from other namespaces in your headers, fully qualify every name. It can be a pain sometimes, but it's really the right thing to do.

Examples:

// WRONG!
using namespace std;
class MyClass
{
    string stringVar;
};

// RIGHT
class MyClass
{
    std::string stringVar;
};

As for forward declarations of classes in other namespaces, you've got it exactly right. Just remember to always qualify AnotherFoo as AnotherNameSpace::AnotherFoo when you reference it inside your header. Indeed, forward declarations are the only way to break cyclic dependencies.

Answer 2

Regarding #1, I am not aware of any concrete argument for or against. Many companies have a policy where the copyright notice has to be the first item in the file BEFORE anything else or any meaningful code (maybe the assumption is that you'll read the copyright before you absorb any code). For that purpose, #IFNDEF is already code. From a usability point of view, it makes sense to put the copyrights first because the eye ignores them. However, anything describing the module should come after the #ifndef in my opinion.

Answer 3

1) Since comments don't actually do anything, I doubt it matters much. Technically though, #include copy and pastes, so putting the comments outside the header guards can mean more work for the preprocessor. I don't know if most compilers are smart enough to optimize for this (i.e. if they strip comments before the preprocessor step) but you probably wouldn't notice until you reached tens of thousands of header files.

2) That's correct. If you want to put a class inside a namespace, and that class is going to get declared in a header file, well then it should be declared inside the namespace, which thus should be in the header file. And yes, that's how you forward declare exactly. And yes, it is the main tool for avoid cyclic dependency (you could also change your design, but there's nothing wrong with cyclicness in principle provided the two classes in question are only referring to each other by reference or pointer and not calling any methods).

Answer 4

1. I've heard that having comments before the include guard can cause some compilers to miss an optimization. If the guard is the very first thing, the compiler may recognize the idiom and not even bother opening the header for subsequent includes. In my own code, comments normally precede the include guard. I haven't ever bothered testing to see if this has any impact or not. And I likely never will (but if someone else does, I'd be interested in the results).

2. Of course headers should incorporate namespaces - otherwise nothing useful could ever be inside a namespace. However, as you mentioned, headers should not 'import' (for want of a better word) namespaces into a compilation unit with a 'using' directive.

Answer 5

1. I don't think adding comments has any performance impact as pointed by Adam's answer to this post.

2. I have used myself namespaces in header files, what if you define you own string class , so it would clash with the std namespace string class.

Using the "using" keyword exactly is not wrong (since it gives you a lot of convenience and lot less to type before all your variables)