How Anal Is That?

How do you order your #includes at the top of a cpp file?  You probably don't care, because it mostly doesn't matter.  But, for whatever reason, I care.  First the precompiled header header, of course.  Then a linefeed.  Then I like putting the matching .h file first, because if that .h file needs any other .h files, we'll immediately find out and can include them within that .h file. 

Then another linefeed.  Then the "" headers.  Our headers.  In alphabetical order.  How anal is that?  I guess I like structure.  But it does have one little advantage, that you won't accidentally include the same file twice.  Not that that matters, either, but it does look a little bad if someone sees it.  Then the standard lib <> includes. 

Just thought I'd share.  This isn't something I ask coders on my projects to do, but when I'm working with their files, I sometimes go in and rearrange their headers to suit my whims.

Comments

[Bryan McNett]

got a macro in visual studio that randomly scrambles the order of include files. helps to shake out .h files that don't include everything they need.

[Brian Watt]

I follow most of what you said and totally agree with it, but an example would help.

For example, given foo.cpp that uses bar.cpp and iostream I would assume the following formatted #includes:

#include "foo.h"
#include "bar.h"
#include <iostream>

My questions are (1) what is a "matching .h file", (2) do the linefeeds represent the end of the #include line or a blank line?

[Ruslan Shestopalyuk]

There are also headers, which might have a different "scope":
- 3rd party libraries'/APIs headers (they are neither standard lib, nor "ours")
- "our" headers, which are interfaces to other modules in our program, not the current one (e.g. math library headers included into the rendering module's .cpp
- sometimes there are "temporary" (FIXME) includes, which might appear when refactoring the physical structure of the project (or hacking in an extra bad dependency in a hurry, for whatever reason)
- etc

...those groups I would personally prefer to also see clustered together, so headers inside each group correspond to roughly the same "scope".

Also, when "related" headers are close to each other, it appears easier to understand the dependencies in a chunked way (e.g. if #include "MathLib/WaveletTransform.h" and #include "Mathlib/FourierTransform.h" stand together, then from the first glance one can catch the idea that this module is about signal processing, and it's depending on the part of math library, which performs certain signal transformations).

But it's just me, of course. The topic is quite holywar-enabling :)

[kert]

well, for me "precompiled.h" goes at the top.

project-local.h-s "" go next in order of more general to more specific, and then any system.hs ( should these be required ) go last.

[Jim Tilander]

Oh, I got you so beat :) I like to have:

#include "PreCompiled.h"
#include "ThisCurrentModule.h"
#include
#include
#include
#include

So we start out the same, but then I like to have the headers in descending order of dependency. I.e. headers that depend on less should be lower. That way you are forced to make each and every header autonomous, it can stand on it's own.

Although it's of course very hard to keep this up to date. But it itches in my fingers every time I see something that's not matching the pattern :)

[Jim Tilander]

Ahrg, the webpage *ate* my angle brackets! Dang. It was supposed to be:

#include "PreCompiled.h"
#include "ThisCurrentModule.h"
#include <HighLevelLibrary/HighLevelLibrary.h>
#include <Math/Vector.h>
#include <Core/Types.h>
#include <string.h>

[Liam]

Standard headers
Third party headers
Matching header
All other required headers
"How anal is that?"
How anal are we all?

[Tassilo Philipp]

I have a single include in every cpp file, namely the PCH. The PCH itself includes all the headers in the right order. Of course, a change to a headers takes some time to recompile, because the entire PCH gets recompiled, but my project is split up into lots of libraries shifting some work to the linker.
This gives me the nice benefit, that I can spot strange dependencies by just looking at the order in which I include the headers in the PCH, and there's literally no parsing overhead. I can actually turn of the include guards, because every header gets included once only.
Not everybody's taste, but it works great for me, clean structure, nicely layered and compilation is faster (as long as the entire project is logically split up into several libs).

[Jamie Fristrom]

I would have kept the "pretty anal" comment if it linked to something relevant.