C/C++ include file order/best practices

Question

Hello.

Is there recommended order in which include files should be specified?

For example, the system files, STL, Boost, go before of after local include files? is there a particular reason to choose one or another? I am assuming include files have proper dependencies specified.

Thanks

Answer 1

This is not subjective. Make sure your headers don't rely on being #included in specific order. You can be sure it doesn't matter what order you include STL or Boost headers.

Answer 2

I don't think there's a recommended order, as long as it compiles! What's annoying is when some headers require other headers to be included first... That's a problem with the headers themselves, not with the order of includes.

My personal preference is to go from local to global, each subsection in alphabetical order, i.e.:

1. h file corresponding to this cpp file (if applicable)
2. headers from the same component,
3. headers from other components,
4. system headers.

My rationale for 1. is that it should prove that each header (for which there is a cpp) can be #included without prerequesites. And the rest just seems to flow logically from there.

Answer 3

I'm pretty sure this isn't a recommended practice anywhere in the sane world, but I like to line system includes up by filename length, sorted lexically within the same length. Like so:

#include <set>
#include <vector>
#include <algorithm>
#include <functional>

I think it's a good idea to include your own headers before other peoples, to avoid the shame of include-order dependency.

Answer 4

I follow two simple rules that avoid the vast majority of problems:

1. All headers (and indeed any source files) should include what they need. They should not rely on their users including things.
2. As an adjunct, all headers should have include guards so that they don't get included multiple times by over-ambitious application of rule 1 above.

I also follow the guidelines of:

1. Include system headers first (stdio.h, etc) with a dividing line.
2. Group them logically.

In other words:

#include <stdio.h>
#include <string.h>

#include "btree.h"
#include "collect_hash.h"
#include "collect_arraylist.h"
#include "globals.h"

Although, being guidelines, that's a subjective thing. The rules on the other hand, I enforce rigidly, even to the point of providing 'wrapper' header files with include guards and grouped includes if some obnoxious third-party developer doesn't subscribe to my vision :-)

Answer 5

I recommend:

1. The header for the .cc module you're building. (Helps ensure each header in your project doesn't have implicit dependencies on other headers in your project.)
2. C system files.
3. C++ system files.
4. Platform / OS / other header files (e.g. win32, gtk, openGL).
5. Other header files from your project.

And of course, alphabetical order within each section, where possible.

Always use forward declarations to avoid unnecessary #includes in your header files.

Answer 6

First include the header corresponding to the .cpp... in other words, source1.cpp should include source1.h before including anything else. The only exception I can think of is when using MSVC with pre-compiled headers in which case, you are forced to include stdafx.h before anything else.

Reasoning: Including the source1.h before any other files ensures that it can stand alone without it's dependencies. If source1.h takes on a dependency on a later date, the compiler will immediately alert you to add the required forward declarations to source1.h. This in turn ensures that headers can be included in any order by their dependants.

Example:

source1.h

class Class1 {
    Class2 c2;    // a dependency which has not been forward declared
};

source1.cpp

#include "source1.h"    // now compiler will alert you saying that Class2 is undefined
                    // so you can forward declare Class2 within source1.h
...

MSVC users: I strongly recommend using pre-compiled headers. So, move all #include directives for standard headers (and other headers which are never going to change) to stdafx.h.

Answer 7

I consider this a purely stylistic concern, since headers should have as few dependencies as possible, and consequently forward-declare as much as possible, relying on source files to supply dependencies for what they actually use non-referentially. Basically the only time I ever include something in a header is when the needed class cannot be forward-declared, which is the case pretty much exclusively for system headers and inherited classes. You can get around the whole issue of inclusion order by designing your headers correctly in the first place.

So, for the sake of having some arbitrary consistent order, I write #includes top-down:

• System headers.
• Boost headers.
• Library headers.
• Project headers.

Each section is sorted lexicographically, case-sensitively: files beginning with a come after those beginning with Z. Since my class headers are in CamelCase and utility headers are in lowercase, these naturally fall into groups within the project headers. The header for the class that is implemented in the including source file has no special significance and is sorted along with other project headers.

You can introduce implicit dependencies this way. It is not foolproof. But defensive programming is really fearful programming, and the only way to quit being a fool when programming is to program without fear, accept the consequences for doing it wrong, and learn from your mistakes.

Answer 8

Include from the most specific to the least specific, starting with the corresponding .hpp for the .cpp, if one such exists. That way, any hidden dependencies in header files that are not self-sufficient will be revealed.

This is complicated by the use of pre-compiled headers. One way around this is, without making your project compiler-specific, is to use one of the project headers as the precompiled header include file.

Answer 9

To add my own brick to the wall.

1. Each header needs to be self-sufficient, which can only be tested if at least once it's included first
2. One should not mistakenly modify the meaning of a 3rd party header by introducing symbols (macro, types, etc...)

So I usually go like this:

// myproject/src/example.cpp
#include "myproject/example.h"

#include <algorithm>
#include <set>
#include <vector>

#include <3rdparty/foo.h>
#include <3rdparty/bar.h>

#include "myproject/another.h"
#include "myproject/specific/bla.h"

#include "detail/impl.h"

Each group separated by a blank line from the next one:

• Header corresponding to this cpp file first (sanity check)
• system headers
• 3rd party headers, organized by dependency order
• project headers
• project private headers

Also note that apart from system headers each file is in a folder that with the name of its namespace, just because it's easier to track them down this way.