Opinions on include order and coding standards

[Adrian]

Hi All,

Just wondering if people have any opinions on how include's should be
ordered. Personally I use style A. Are there any practical reason for
either style. I assume both would have about the same compile time, so
no savings there.

Style A
#include <c++, system headers>
#include <library headers>
#include "local headers"

Style B
#include "local headers"
#include <library headers>
#include <c++, system headers>

Also what should be the goals of, or included in, a c++ coding
standard. I think they should be, (not in any order)
1. Standard and portable behavior
2. Readability of code
3. Best practices

As you may have guessed we are changing our internal coding standards.


Adrian

 

[Niels Dekker - no return address]

Style A
#include <c++, system headers>
#include <library headers>
#include "local headers"

Style B
#include "local headers"
#include <library headers>
#include <c++, system headers>

I'm doing style B, because a local header include should not need a library
headers to be included first. Style B allows the compiler to double-check that
the local headers are indeed self-contained.

Also what should be the goals of, or included in, a c++ coding
standard.

C++ FAQ Lite warns you against posting such questions:
www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.1
But anyway, no problem...

I think they should be, (not in any order)
1. Standard and portable behavior

Depends on the system you're building. If you're only programming for one
specific platform and one specific compiler, it might be worthwhile to
optimize the code for your platform, and use platform-specific tricks...

2. Readability of code

Very important. Unfortunately, it's hard to write code that's readable to
guru's and dummies alike... So the essential question is: who're going to
read your code?

3. Best practices

I'd say, follow the guidelines from books like Effective C++ (Scott Meyers)
and C++ Coding Standards (Herb Sutter & Andrei Alexandrescu), "by default".
If a certain piece of code doesn't follow those guidelines, clearly document
why!

Success,

Niels

 

[Martin York]

Hi All,

Just wondering if people have any opinions on how include's should be
ordered. Personally I use style A. Are there any practical reason for
either style. I assume both would have about the same compile time, so
no savings there.

Style A
#include <c++, system headers>
#include <library headers>
#include "local headers"

Style B
#include "local headers"
#include <library headers>
#include <c++, system headers>

Also what should be the goals of, or included in, a c++ coding
standard. I think they should be, (not in any order)
1. Standard and portable behavior
2. Readability of code
3. Best practices

As you may have guessed we are changing our internal coding standards.

Adrian

As Niel describes above, agree with all of it.
In addition I apply the following rule (note these are just my
opinion).

Header that contain most specific declarations first.
Degrading to headers with most generic declarations.

A trivial example:
You have container(C) of A
#include <A.h>
#include <C.h>

The only exception to the rule (and there must be exceptions to make
it a rule
include the header file for this specific source file first.

F.cpp
#include "F.h"

// Other header files.

Finally try and push #includes out of header files into source files
and use forward declaration were possible. eg. Class A contains a
reference to B.

A.h

class B; // Forward declare. don't use #include
class A { B& b; /* STUFF */};

A.cpp
#include "A.h"
#include "B.h"

// Code

 

[Victor Bazarov]

Just wondering if people have any opinions on how include's should be
ordered. Personally I use style A. Are there any practical reason for
either style. I assume both would have about the same compile time, so
no savings there.

Style A
#include <c++, system headers>
#include <library headers>
#include "local headers"

Style B
#include "local headers"
#include <library headers>
#include <c++, system headers>

Also what should be the goals of, or included in, a c++ coding
standard. I think they should be, (not in any order)
1. Standard and portable behavior
2. Readability of code
3. Best practices

As you may have guessed we are changing our internal coding standards.

Here is my twopence: the order shouldn't matter. If your order matters,
you are doing something WRONG.

V

 

[Krice]

If your order matters, you are doing something WRONG.

I have lots of headers that must be included in specific
order. If the order has no meaning then you could place
includes anywhere in the source file.

 

[James Kanze]

I have lots of headers that must be included in specific
order.

Then you're doing something wrong.

If the order has no meaning then you could place includes
anywhere in the source file.

Not anyplace. The include must be at global scope, and before
anything in the header is used. Otherwise, though, yes. It's
just a convention to put all of the includes at the top.

 

[Krice]

and before anything in the header is used.

I have base class headers which are included before derived
class header (no forward declarations). Is that wrong?

 

[Bo Persson]

I have base class headers which are included before derived
class header (no forward declarations). Is that wrong?

Your other choice is to include the base class header in the derived
class' header. That way you always get the right order.


Bo Persson

 

[James Kanze]

I have base class headers which are included before derived
class header (no forward declarations). Is that wrong?

You shouldn't have to include the base class headers at all if
you're using the derived class. The general rule for well
written headers is:

-- a source file consisting of just an include of this one
header should compile without errors, and

-- client code can include the headers as often as it wants, in
any order, without problems.

The acceptable restrictions for headers are the unavoidable
ones: they must be included before anything declared in them is
used, and they must be included at global scope, outside of any
namespaces, class definitions or function definitions. And, of
course, nothing which precedes them may define a macro for a
symbol used in the header---this is normally handled by
requiring all macro names to be all caps, and forbidding
anything else to be all caps.

 

[Martin York]

Here is my twopence: the order shouldn't matter. If your order matters,
you are doing something WRONG.

Exactly true.

And by enforcing a certain order you can expose these types of
problems were there is a dependency and thus force a fix earlier in
the development cycle. A logical ordering also helps with
maintainability and code refactoring a couple of years down the road,
then good ordering can help simplify the problem of upgrading for the
poor next person that has to go and fix your bugs.

There is no reason to make the next persons job harder by hiding
potential problems. So try and force them out early in the development
cycle so they can be fixed.

 

[Sherman Pendley]

You shouldn't have to include the base class headers at all if
you're using the derived class. The general rule for well
written headers is:

-- a source file consisting of just an include of this one
header should compile without errors, and

-- client code can include the headers as often as it wants, in
any order, without problems.

That's two rules.

I'll add a third:

-- Minimize inter-header dependencies as much as possible. Don't use
#include in a header when a forward class declaration will suffice.

sherm--

 

[Krice]

fix your bugs.

I have made several programs with that kind of "wrong" include
style and they compile and work perfectly.

 

[James Kanze]

I have made several programs with that kind of "wrong" include
style and they compile and work perfectly.

But of course, they're a maintenance nightmare.

 

[Yannick Tremblay]

I'm doing style B, because a local header include should not need a library
headers to be included first. Style B allows the compiler to double-check
that the local headers are indeed self-contained.

I agree. All header file should be complete.

Essentially, the following should always compile:
------------------------
#include "my header"
int main()
{
return 0;
}
------------------------

IMO, if this fails to compile but you need to do this to compile:
----------------------------
#include <some other header>
#include "my header"
int main()
{
return 0;
}
----------------------------

Then "my header" is incorrect.

Although Victor is correct that all headers should be order
independent (it should be possible to include any header in any order,
any number of time and still compile, maybe we need a code generator
than randomly include all header file in a system and test for
compilation , I find that using a convention
that a class implementation file always include it's class declaration
header file first useful for early detection of incomplete
headers. i.e.

MyClass.cpp
------------------------
#include "Myclass.hpp"
#include <whatever else>

....
------------------------

This allows to be certain that if Myclass.cpp compiles, then any
client that wish to #include MyClass.hpp will be able to do so at no
additional cost of figuring out the 13 different system headers that
must be included beforehand.

Yannick