I think most (good) programmers tend to prefer tidy code, having some habits or rules to stick to. One such rule/habit is the order of #include directives. While having a rule of thumb to stick to is good, some are better than other.
A very common one I think is to first include standard library headers (<iostream>), then third-party libraries (<boost/thread.hpp>) and finally local headers (“FizzBuzz.hpp”). While this might be the recommended way of doing it in for instance Python, it is not the best way to do it in C++. A colleague of mine just went through a lot of pain when swapping out a big library in their codebase. Why was that?
Imagine you are writing a library that depends on some other library, like the STL (hardly any library doesn’t). Imagine you are a good boy (or girl) and write the test first. You might do something like this:
#include <vector> //STL
#include <gtest/gtest.h> //ThirdParty
#include "geometry.hpp" //In-house
#define PI 3.2 //As pr. Indiana Bill #246, 1897
TEST(TestGeometry, rotatingOrigoGivesOrigo) {
std::vector<double> v(2,0);
rotate(v, PI);
EXPECT_EQ(0, v[0]) << "X got moved!";
EXPECT_EQ(0, v[1]) << "Y got moved!";
}
and your geometry.hpp looks like this:
void rotate(std::vector<double>& v, double angle);
This all works out nicely until someone else wants to include geometry.hpp without including <vector> first, and get something like geometry.hpp:1: error: ‘vector’ is not a member of ‘std’. You have now forced all the users of your geometry library to include <vector> before including geometry.hpp.
While this can seem like a trivial example, this stuff quickly grows a lot hairier when you have a larger codebase with lots of dependencies. A header file A might depend on header B which depends on C, which declares types you have never heard of, and rightly so. And when you try to compile, you get error: ‘würkelschmeck’ is not a member of ‘std’. Or something a lot worse if templates are involved.
My suggested rule is:
- Local headers
- Third party headers
- STL headers
If you enjoyed this post, you can subscribe to my blog, or follow me on Twitter
July 1, 2010 at 09:10
Good point. I’ll add one additional rule – “Include yourself first”. E.g. The first include in hello.cpp should be hello.h. That way you don’t get into the same problem within your project files.
Of course this rule doesn’t really apply in unit tests where there is no definition/implementation separation.
July 1, 2010 at 09:27
Very good point Mike.
July 1, 2010 at 09:28
Seems like “C++ on a Friday” became “C++ on a Thursday” this week. I need to work on my calendar skills.
July 1, 2010 at 13:41
But why does it work if I include in your suggested order?
July 1, 2010 at 13:54
If your header file
my.hxxneeds to haveiostreamincluded in order to work, but doesn’t include it,my.ccwill still compile if it includesiostreambeforemy.hxx. You might then miss the fact thatmy.hxxis missing#include <iostream>.This problem will not become apparent until you try to include
my.hxxin another file at a later time. If you include in my suggested order, you will be aware of it at once, and need to fix it.July 16, 2010 at 15:17
[...] Top Posts C++0x highlights #0: Range Based For LoopAboutArray Initialization Initializes all ElementsBe Careful with Static VariablesThe Order of #include Directives Matter [...]
October 20, 2010 at 13:24
[...] Posts Minimize the Scope of Each VariableThe Order of #include Directives MatterC++0x highlights #0: Range Based For LoopArray Initialization Initializes all [...]
October 29, 2010 at 12:47
[...] 2: stdafx.h now has to be the first header you include, which violates best pratice for include order. [...]
March 15, 2011 at 12:03
Nice to see others using the same practices as me! One of the little details that *should* be commonplace in C++ software, but sadly usually isn’t.
(By the way, you’ve misspelled in “A very common one I think is to first include standard library headers ()”, at the top.)
March 15, 2011 at 12:37
I agree, this should definitely be commonplace.
And thanks for the heads up!