C++ Header order

Question

What order should headers be declared in a header / cpp file? Obviously those that are required by subsequent headers should be earlier and class specific headers should be in cpp scope not header scope, but is there a set order convention / best practice?

Answer 1

I used to order them in alphabetical order (easier to find)

Answer 2

It's a dependency thing and it depends largely on what you put in our headers. A fact is that you can be really notorious about this and minimize to keep your includes strict but you'll eventually run into a scenario where you'll wanna use inclusion guards.

#ifndef MY_HEADER_H
#define MY_HEADER_H
//...
#endif

The problem isn't that apparent in the beginning, but as the complexity of your software grows so does your dependencies. You can do well, and be smart about it but larger C++ projects are generally riddled with includes. You can try, but you can only do so much. So be diligent and think about your includes, YES! But you'll most certainly have cyclic dependencies at some point and that is why you need inclusion guards.

Answer 3

Good practice: every .h file should have a .cpp that includes that .h first before anything else. This proves that any .h file can be put first.

Even if the header requires no implementation, you make a .cpp that just includes that .h file and nothing else.

This then means that you can answer your question any way you like. It doesn't matter what order you include them in.

For further great tips, try this book: Large-Scale C++ Software Design - it's a shame it's so expensive, but it is practically a survival guide for C++ source code layout.

Answer 4

In a header file you have to include ALL the headers to make it compilable. And don't forget to use forward declarations instead of some headers.

In a source file:

• corresponded header file
• necessary project headers
• 3rd party libraries headers
• standard libraries headers
• system headers

In that order you will not miss any of your header files that forgot to include libraries by their own.

Answer 5

For .cpp files, you should include the header of the class or whatever you are implementing first, so you catch the case where this header is missing some includes. After that, most coding guidelines tend to include system headers first, project headers second, for example the Google C++ Style Guide.

Answer 6

If a header needs other headers then it just includes them in that header.

Try to structure your code so you pass pointers or references and forward declare where you can.

In the implementation then the header that defines it should be listed first (except in Visual Studio if you are using pch then stdafx would go first).

I generally list them as I need.

Answer 7

In header files, I tend to put standard headers first, then my own headers (both lists being ordered alphabetically). In implementation files, I put first the header corresponding (if any), then standards headers and other dependency headers.

Order is of little importance, except if you make a great use of macros and #define ; in that case, you must checked that a macro you defined doesn't replace a previously included one (except if that's what you want, of course).

Concerning this statement

those that are required by subsequent headers should be earlier

A header shouldn't rely on other headers being included before it! If it requires headers, it just includes them. Header guards will prevent multiple inclusion:

#ifndef FOO_HEADER_H
#define FOO_HEADER_H
...
#endif

Answer 8

I've found the following convention the most useful:

module.cpp:

// this is the header used to trigger inclusion of precompiled headers
#include <precompiled.h> 
// this ensures that anything that includes "module.h" works
#include "module.h"
// other headers, usually system headers, the project

The important thing is to put the module's header as the first non-precompiled header. This ensures "module.h" has no unexpected dependencies.

If you're working on a large project with slow disk access times, I've seen this style used to decrease build times:

module.cpp:

// this is the header used to trigger inclusion of precompiled headers
#include <precompiled.h> 
// this ensures that anything that includes "module.h" works
#include "module.h"
// other headers, usually system headers, the project
#if !defined _OTHER_MODULE_GUARD_
#include "other_module.h"
#endif 

#if !defined _ANOTHER_MODULE_GUARD_
#include "another_module.h"
#endif

It's a bit verbose but does save on disk seeking since the header won't be searched for / opened if it's already been included. Without the guard check, the compiler will seek for and open the header file, parse the whole file to end up #ifdef'ing the whole file out.

Skizz

Answer 9

Whatever your order in the CPP files, never include H files inside other H files.
It can become spaghetti very quickly.

---

EDIT
Exception to the above is if a class is derived from a class in another H file - in which case you must include the parent H file in the child H file.

Answer 10

The "how" is not obvious, but the "what" is. Your goal is to make sure that the order in which you include header files never matters (and i mean "NEVER !").

A good help is to test whether header files compile when building cpp files (one for each header file) that only include one of them.

Answer 11

Google C++ Style Guide, Names and Order of Includes :

In dir/foo.cc, whose main purpose is to implement or test the stuff in dir2/foo2.h, order your includes as follows:

• dir2/foo2.h (preferred location — see details below).
• C system files.
• C++ system files.
• Other libraries' .h files.
• Your project's .h files.