C/C++ include header file order

The Question :

295 people think this question is useful

What order should include files be specified, i.e. what are the reasons for including one header before another?

For example, do the system files, STL, and Boost go before or after the local include files?

The Question Comments :
  • And the plethora of answers below is why the Java developers decided against separate headers. 🙂 Some really good answers, however, particularly the admonition to make sure your own header files can stand alone.
  • I like it how questions that have 100+ votes and are obivously interesting for quite some people get closed as “not constructive”.
  • A highly recommended read: cplusplus.com/forum/articles/10627
  • @mrt, SO strongly reminds of the soup Nazi community: Either you follow some very strict rules, or “No proper Answer/Comments for you!”. Nonetheless, if someone has a problem related in any way to programming, this is (usually) the first site to go..

The Answer 1

301 people think this answer is useful

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 prerequisites (terminus technicus: header is “self-contained”). And the rest just seems to flow logically from there.

The Answer 2

113 people think this answer is useful

The big thing to keep in mind is that your headers should not be dependent upon other headers being included first. One way to insure this is to include your headers before any other headers.

“Thinking in C++” in particular mentions this, referencing Lakos’ “Large Scale C++ Software Design”:

Latent usage errors can be avoided by ensuring that the .h file of a component parses by itself – without externally-provided declarations or definitions… Including the .h file as the very first line of the .c file ensures that no critical piece of information intrinsic to the physical interface of the component is missing from the .h file (or, if there is, that you will find out about it as soon as you try to compile the .c file).

That is to say, include in the following order:

  1. The prototype/interface header for this implementation (ie, the .h/.hh file that corresponds to this .cpp/.cc file).
  2. Other headers from the same project, as needed.
  3. Headers from other non-standard, non-system libraries (for example, Qt, Eigen, etc).
  4. Headers from other “almost-standard” libraries (for example, Boost)
  5. Standard C++ headers (for example, iostream, functional, etc.)
  6. Standard C headers (for example, cstdint, dirent.h, etc.)

If any of the headers have an issue with being included in this order, either fix them (if yours) or don’t use them. Boycott libraries that don’t write clean headers.

Google’s C++ style guide argues almost the reverse, with really no justification at all; I personally tend to favor the Lakos approach.

The Answer 3

49 people think this answer is useful

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 🙂

The Answer 4

22 people think this answer is useful

To add my own brick to the wall.

  1. Each header needs to be self-sufficient, which can only be tested if it’s included first at least once
  2. One should not mistakenly modify the meaning of a third-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
  • Third-party headers, organized by dependency order
  • Project headers
  • Project private headers

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

The Answer 5

16 people think this answer is useful

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.

The Answer 6

14 people think this answer is useful

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.

The Answer 7

6 people think this answer is useful

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.

The Answer 8

4 people think this answer is useful

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.



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


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

The Answer 9

2 people think this answer is useful

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.

The Answer 10

1 people think this answer is useful

It is a hard question in the C/C++ world, with so many elements beyond the standard.

I think header file order is not a serious problem as long as it compiles, like squelart said.

My ideas is: If there is no conflict of symbols in all those headers, any order is OK, and the header dependency issue can be fixed later by adding #include lines to the flawed .h.

The real hassle arises when some header changes its action (by checking #if conditions) according to what headers are above.

For example, in stddef.h in VS2005, there is:

#ifdef  _WIN64
#define offsetof(s,m)   (size_t)( (ptrdiff_t)&amp;(((s *)0)->m) )
#define offsetof(s,m)   (size_t)&amp;(((s *)0)->m)

Now the problem: If I have a custom header (“custom.h”) that needs to be used with many compilers, including some older ones that don’t provide offsetof in their system headers, I should write in my header:

#ifndef offsetof
#define offsetof(s,m)   (size_t)&amp;(((s *)0)->m)

And be sure to tell the user to #include "custom.h" after all system headers, otherwise, the line of offsetof in stddef.h will assert a macro redefinition error.

We pray not to meet any more of such cases in our career.


Add a Comment