[C++] Order of header inclusion

[qazmlp]

I need to include a list of
- C++ headers
- headers of other modules
- headers of my module
- implementation specific ie.OS headers


In what order, they should be included in my .CPP file? What is the
best followed approach?

 

[Attila Feher]

I need to include a list of
- C++ headers
- headers of other modules
- headers of my module
- implementation specific ie.OS headers


In what order, they should be included in my .CPP file? What is the
best followed approach?

It is all just one opinion:

It is a common rule to include first the standard headers.

Then you include the header for the implementation (like for the class),
which in turn includes all the headers needed for the declaration.

Then you include any additional headers needed for the implementation.

IIRC the only "rule" I have heard is to include the standard headers first.
The cause for this rule is that if there is something "wrong" in your
headers they cannot accidentaly modify the meaning of the standard headers.
Of course, since the other headers might also include standard headers it
can never really be done that all standard headers are included first.

IMHO the order of inclusion is usually a matter of taste. Each header file
in itself must "work" without any other header included before (meaning that
it should include the needed headers, predeclare the needed incomplete types
etc.) So as long as you have no "errors" it is rather a matter of personal
taste and readibility. For example people usually do not mix those headers,
so they first include the standard ones (usually C and C++ headers separated
by a blank line), then (let's say) the OS headers, then the possibly the
other headers needed by the implementation, then the implementation's own
header. I know, it is a different order than I have said before - that is
the reason why I have said that it is /mostly/ a matter of taste or personal
style.

 

[Shane Beasley]

It is all just one opinion:

It is a common rule to include first the standard headers.

Then you include the header for the implementation (like for the class),
which in turn includes all the headers needed for the declaration.

Then you include any additional headers needed for the implementation.

I do the opposite: I include the primary header (with declarations to
be defined in the .cpp file), then other project headers, then system
headers (anything outside my project) in an organized but admittedly
arbitrary order.

With my way, I know if I forgot to include another header in one of
mine because mine is included first. With yours, my header may be
included after other headers it needs, thus making them available even
though mine didn't include them itself.

IIRC the only "rule" I have heard is to include the standard headers first.
The cause for this rule is that if there is something "wrong" in your
headers they cannot accidentaly modify the meaning of the standard headers.

How, beyond macros, can you modify a header by defining things
yourself first? If that's the only way, you'd almost have to go out of
your way to do such a thing.

IMHO the order of inclusion is usually a matter of taste.

Absolutely correct for well-written headers. Defending against other
people's poorly-written headers is better done on a case-by-case basis
than by rule of thumb. On the other hand, defending against your own
headers can best be done using my order of inclusion (IMO).

- Shane

 

[Attila Feher]

Shane Beasley wrote:
[SNIP]

With my way, I know if I forgot to include another header in one of
mine because mine is included first. With yours, my header may be
included after other headers it needs, thus making them available even
though mine didn't include them itself.

Correction: with the practice I have mentioned. I have never told it is
mine. But since it has been presented as a common coding rule to me on many
occasions (ACCU conference was one of them) I thought I introduce it here.

How, beyond macros, can you modify a header by defining things
yourself first? If that's the only way, you'd almost have to go out of
your way to do such a thing.

I have never done such a thing. That was what has been named as a reason
for the coding rule.

Absolutely correct for well-written headers.

That is what I have said.

Defending against other
people's poorly-written headers is
better done on a case-by-case basis
than by rule of thumb.

The idea is not protecting against them but to make finding them simple.
Meaning that if there is a 3rd party product and you include its headers you
may not be able to diff all the headers to figure out that one of them does
something wrong after the update. So this header inclusion order thing is
for ease of finding mistakes in (I guess) 3rd party code, not for finding
mistakes in the code we are in charge of (and have tested, unit tested, code
reviewed etc.).

To be honest as I work at the workplace is to follow the existing
practices - if they suffice.

On the other hand, defending against your own
headers can best be done using my order of inclusion (IMO).

I agree. Defending against missing standard headers (and error I have seen)
is a bit better, but since there might be other (your) headers before that
including the right std (or system) header or one which includes it... this
is not a foolproof test either. That is why I dared to say: it is rather a
matter of taste. But I am open to hear if anyone has a good argument for a
certain inclusion order.

 

[Greg C]

I need to include a list of
- C++ headers
- headers of other modules
- headers of my module
- implementation specific ie.OS headers


In what order, they should be included in my .CPP file? What is the
best followed approach?

Switch to a language that doesn't use header files?

 

[Andre Kostur]

One of the stupid things of file inclusion is that you cannot keep
track of the dependencies. For example some of my source files compile
fine on some compilers but not on other due to my neglegance in
including the appropriate headers. In one compiler the required
dependency comes through some other header by luck, and in the other
it doesn't.

I haven't yet managed to find a good solution to that other than
compiling my source on various compilers (and accompanying standard
library implementations).

The good solution is to always include the headers needed for your uses,
and to not assume that one header will include another, unless it is
explicitly documented (ie: in the Standard, not in the header files) that
it will do so.

 

[White Wolf]

Greg C wrote:
[SNIP]

Switch to a language that doesn't use header files?

First please switch newsgroup.

 

[E. Robert Tisdale]

I need to include a list of
- C++ headers
- headers of other modules
- headers of my module
- implementation specific ie.OS headers


In what order, they should be included in my .CPP file?
What is the best followed approach?

It doesn't matter which order you include header files
if they are both self sufficient and idempotent.


"Public header files should be

1. self sufficient and
2. idempotent.

Self sufficient means that
no other header files or definitions need to be included
before you include the public header file.
Idempotent means that
the content of the public header file is included no more than once
regardless of how many times it is included by other header files.

Nor should public header files include any statements
that cause the compiler to generate code or allocate memory."

 

[John L Fjellstad]

I need to include a list of
- C++ headers
- headers of other modules
- headers of my module
- implementation specific ie.OS headers


In what order, they should be included in my .CPP file? What is the
best followed approach?

I like to include the header for this .cpp file first. This way, the
compiler will complain if my header file is missing some forward
declarations or header files. Also, it means that if other people use my
header file, it is guaranteed to work no matter which order they include
the file.

The rest is random, but I like to group them together, and the C++ headers
come first.

 

[Andre Kostur]

Its not easy to keep track of which headers your source files need.
When one standard header includes another (in a non-standard way) its
very easy to miss the dependency your code has on that header.

Well.... then one should be adding the header for any new stuff that you
use (ie: I just added an std:stringstream in my program, I should go add
#include <sstream> to my list of headers....). As opposed to adding new
stuff, then adding headers until it compiles.... (Now, granted, I'm guilty
of this method too.... but in a _perfect_ world )