Header files and include best practice

Question

I have a quick question regarding header files, include statements, and good coding style. Suppose I have 2 classes with associated source and header files, and then a final source file where main() is located.

Within Foo.hpp I have the following statements:

#include <string>
#include <iostream>
#include <exception>

Now withing Bar.hpp I have the following statements:

#include "Foo.hpp"
#include <string>

And finally withing Myprogram.cpp I have the following statements:

#include "Bar.hpp"
#include <string>
#include <iostream>
#include <exception>

I know the include statements in <> in Myprogram.cpp and Bar.hpp aren't necessary for the program to compile and function, but what is the best practice or right way of doing things? Is there any reason to not explicitly include the necessary header files in each file?

Solution 1

You should include all necessary files in every file that needs them. If MyProgram.cpp needs string, include it, instead of relying on it being included by Bar.hpp. There's no guarantee 2 weeks from now Bar.hpp will still include it, and then you'll be left with compiler errors.

Note the necessary - i.e. make sure you actually need an include, when a forward declaration or even leaving it out completely will do.

Also, note that some system headers might include others - apart from a few exceptions, there's no requirement. So if you need both <iostream> and <string> include both, even if you can compile only with one of them.

The order in which the includes appear (system includes vs user includes) is up to the coding standard you follow - consistency is more important than the choice itself.

Solution 2

Include all you need in every file, but do not include any file that you do not need. Normally, it is the job of the included file to make sure it is not included twice, using precompiler flags, etc...

For example if is needed by Foo.cpp, but not by Foo.h, include it in Foo.cpp not in Foo.h. If required in both, include in both.

Tangentially, as a best practice, never use using directives in a header file. If you need you can use using directives in implementation files (.cpp).

Comments

[Martin York]

In "Foo.hpp" do you use strings, streams or exceptions?

[Martin York]

But the inverse is also true, you should not include header files (in a header) unless you do need them (ie don't over include).

[Neutrino]

I think it makes sense to add system includes before user includes as you never know when some developer down the line is going to add a macro to a user header that might break a system header.