« Look At My Ugly Code | Main | The Curtain Problem »

August 05, 2009


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 :)


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"

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>


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.

The comments to this entry are closed.

Jamie's Bragging Rights

  • Spider-Man 2
    The best superhero games of all time Game Informer
    Top five games of all time Yahtzee Croshaw
    Top five superhero games of all time MSNBC
    Top 100 PS2 games of all time Official Playstation 2 Magazine
    1001 Games You Must Play Before You Die Nomination for Excellence in Gameplay Engineering Academy of Interactive Arts & Sciences
  • Schizoid
    Penny Arcade PAX 10 Award
    Nominated for XBLA Best Original Game
    Nominated for XBLA Best Co-Op Game