Order of #includes

[Chris Gordon-Smith]

I am currently revisiting the code of a C++ application and restructuring
the code where appropriate to make it consistent with the overall logical
design.

As part of this, I am looking at the way .cpp files #include headers. My
question is this: Is there a standard order in which heders should be
included?

I tend to #include STL headers first, and my own headers later, but I can't
really think of a logical justification for this.

Any thoughts welcome.

Chris Gordon-Smith
London
Homepage: http://graffiti.virgin.net/c.gordon-smith/

 

[Victor Bazarov]

I am currently revisiting the code of a C++ application and restructuring
the code where appropriate to make it consistent with the overall logical
design.

As part of this, I am looking at the way .cpp files #include headers. My
question is this: Is there a standard order in which heders should be
included?

Which headers are we talking about? If it's the standard headers, like
<iostream> or <functional> or <list>, then no, order is unimportant.

If that's your own headers, then we have no idea. Although from the coding
style and overall maintainability of the code point of view, if there _is_
order dependency between your headers, it's A BAD THING(tm).

I tend to #include STL headers first, and my own headers later, but I
can't
really think of a logical justification for this.

There isn't any.

V

 

[Cy Edmunds]

I am currently revisiting the code of a C++ application and restructuring
the code where appropriate to make it consistent with the overall logical
design.

As part of this, I am looking at the way .cpp files #include headers. My
question is this: Is there a standard order in which heders should be
included?

I tend to #include STL headers first, and my own headers later, but I
can't
really think of a logical justification for this.

Any thoughts welcome.

Chris Gordon-Smith
London
Homepage: http://graffiti.virgin.net/c.gordon-smith/

One of the many things I learned in this newsgroup is that there is a slight
advantage to including your own headers first and any standard library
headers later. Reason: your own header ought to have included any libraries
they use already. Otherwise they will only work in a certain include order
which, as Victor says, is a Bad Thing.

I don't think it's a big deal, but putting your own headers first is a
modest sort of software test, and software can't be tested too much.

 

[Chris Gordon-Smith]

One of the many things I learned in this newsgroup is that there is a
slight advantage to including your own headers first and any standard
library headers later. Reason: your own header ought to have included any
libraries they use already. Otherwise they will only work in a certain
include order which, as Victor says, is a Bad Thing.

I don't think it's a big deal, but putting your own headers first is a
modest sort of software test, and software can't be tested too much.

Thanks for this. One thing I try to do is to avoid #including header files
from within other header files. This means that I don't write header files
that rely on header files for other classes that I write. Where necessary,
I include forward declarations in my headers. Eg, I might have a header
like this:-

class My_Class; // Forward declaration
class Another_Class
{
public:
void foo(My_Class* bar);
}

I believe that this kind forward declaration doesn't work with STL templates
like <vector>.

Since I don't include headers in my header files, my approach is to have a
standard set of library includes that I put in a file called
Library_Haeders.h. Every one of the source files in my project includes
Library_Headers.h.

I've remembered since my posting yesterday that I originally started using
this approach when I was using C++ Builder. With Borland's compiler its
necessary to organise headers in this way in order for precompiled headers
to work properly. I no longer use Borland, but I'm keeping the
'Library_Headers.h' approach for the moment.

I think that the pros and cons are:-

Pro:-

i) My #include files (except for 'Library_Headers.h' don't need to
#include other #include files
ii) As a result of the above, I can always tell when looking at a source
file what is #included. I don't need to look in other files to see what
they #include.

Con:

i) Since Library_Headers.h includes all of the library headers that are
used in my application, there are many places where more is included than
is really needed.

On balance, I think that the pros outweigh the cons. I regard
Library_Headers.h as, in effect, providing a language extension. The STL
elements it provides are available to all or my source files.

This doesn't seem to be affecting compile times seriously. In any case, if I
did start getting compile time problems, having a standard set of library
includes might become necessary again in order to get pre-compiled headers
working.

 

[Cy Edmunds]

Thanks for this. One thing I try to do is to avoid #including header files
from within other header files. This means that I don't write header files
that rely on header files for other classes that I write. Where necessary,
I include forward declarations in my headers. Eg, I might have a header
like this:-

class My_Class; // Forward declaration
class Another_Class
{
public:
void foo(My_Class* bar);
}

I believe that this kind forward declaration doesn't work with STL
templates
like <vector>.

Since I don't include headers in my header files, my approach is to have a
standard set of library includes that I put in a file called
Library_Haeders.h. Every one of the source files in my project includes
Library_Headers.h.

I've remembered since my posting yesterday that I originally started using
this approach when I was using C++ Builder. With Borland's compiler its
necessary to organise headers in this way in order for precompiled headers
to work properly. I no longer use Borland, but I'm keeping the
'Library_Headers.h' approach for the moment.

I think that the pros and cons are:-

Pro:-

i) My #include files (except for 'Library_Headers.h' don't need to
#include other #include files
ii) As a result of the above, I can always tell when looking at a source
file what is #included. I don't need to look in other files to see what
they #include.

Con:

i) Since Library_Headers.h includes all of the library headers that are
used in my application, there are many places where more is included than
is really needed.

On balance, I think that the pros outweigh the cons. I regard
Library_Headers.h as, in effect, providing a language extension. The STL
elements it provides are available to all or my source files.

This doesn't seem to be affecting compile times seriously. In any case, if
I
did start getting compile time problems, having a standard set of library
includes might become necessary again in order to get pre-compiled headers
working.

Chris, IMHO this is truly a terrible idea. There is nothing wrong with
including headers within headers. But your Library_Headers.h is unduly
obscure (since a third party wouldn't be familiar with it) and forces a
complete recompile of all your source code whenever you change it. Worse
yet, if you decide to reuse your header in a different context years from
now you will have no idea what Library_Headers.h contained.

Writing out all the include files required by a given header is excellent
documentation and makes your code more maintainable and portable. I also
recommend the practice of explicitly including and standard library routines
you are using even if you know darned well that they are already included in
one of your own headers. Again, it's good documentation and won't break if
you decide to implement your header differently.

 

[Michael]

Chris, IMHO this is truly a terrible idea. There is nothing wrong with
including headers within headers. But your Library_Headers.h is unduly
obscure (since a third party wouldn't be familiar with it) and forces a
complete recompile of all your source code whenever you change it. Worse
yet, if you decide to reuse your header in a different context years from
now you will have no idea what Library_Headers.h contained.

Writing out all the include files required by a given header is excellent
documentation and makes your code more maintainable and portable. I also
recommend the practice of explicitly including and standard library routines
you are using even if you know darned well that they are already included in
one of your own headers. Again, it's good documentation and won't break if
you decide to implement your header differently.

I agree with Cy, by making all the source files reference all the header,
just adding a single private member to a header will result in a complete
recompile!
I generally have a file

StdIncludes.h:
//Guard Header

//Global definitions:
#define PLATFORM M_WIN32

//STL Headers:
#include <string>
using std::string;
#include <list>
using std::list;
#include <vector>
using std::vector;

#include <stdlib.h>
#include <math.h>

#define PI 3.414.....f

//End Guard Header

which is referenced but all the .cpp and .h files BUT is unlikely to change,
ie contains none of my own headers!

Mike

 

[Chris Gordon-Smith]

Chris, IMHO this is truly a terrible idea. There is nothing wrong with
including headers within headers. But your Library_Headers.h is unduly
obscure (since a third party wouldn't be familiar with it) and forces a
complete recompile of all your source code whenever you change it. Worse
yet, if you decide to reuse your header in a different context years from
now you will have no idea what Library_Headers.h contained.

Thanks for the comments. I think that we are talking at cross purposes.
Perhaps I should have worded my posting more clearly. The main purpose of
Library_Headers.h is to include headers from the Standard Template Library
(STL). I think therefore that there is nothing obscure, and its contents
will be familiar to any third party (and to me!) in several years time. If
you were thinking that I was including all my own headers in
Library_Headers.h, then I agree that this would indeed be a very bad idea.
Apart from the recompiles you mention, it would make it very difficult to
see which parts of my code depended on which headers; everything would be
visible to everything.

On the point about including headers in headers, I prefer to avoid it as its
easier to understand the dependencies that way. The only place that I do it
in my project is where i have a class that hides its implementation from
clients by having a separate 'protocol' class from which it inherits. The
protocol class has to have its own header file, but the class with the
hidden implementation can't compile unless the protocol class is visible to
it. It therefore makes sense to include the header for the protocol class
from within the header file for the class with the hidden implementation.

Although I agree that there is nothing intrinsically wrong with including
files from within include files, I find it simpler to avoid it except in
such special cases.

Writing out all the include files required by a given header is excellent
documentation and makes your code more maintainable and portable. I also
recommend the practice of explicitly including and standard library
routines you are using even if you know darned well that they are already
included in one of your own headers. Again, it's good documentation and
won't break if you decide to implement your header differently.

I'm currently documenting the relationships between classes in my project.
I'm using the open source product Umbrello, which I find excellent for
drawing UML diagrams. To help with the documentation, I include a
'Relationships' section in each of my header files. This contains class
members that identify objects of other classes. For example, if an object
of class A maintains a pointer to an object of class B, then I place the
declaration of the pointer to B within the Relationships section of the
header for class A. This means that there is then a correspondence between
the relationships shown on my UML diagrams and the Relationships section of
my header file.

Another key kind of relationship is where a class uses another class without
maintaining a pointer. In such cases the dependency relationship is evident
from the code because the user class must include the header for the class
it is using; I can therefore use the #include statements in my code to
determine what dependency relationships I should show on my UML diagrams.
Another reason for not including from within include files is
that such dependencies are clearer. If I know that none of my headers
include other headers, then if a class A includes the header for class B, I
know that this means that A depends on B; I don't have to worry that it
might also be dependent on something else included by the header for B.

 

[Chris Gordon-Smith]

Cy Edmunds wrote:

[snip]

As part of this, I am looking at the way .cpp files #include headers. My
question is this: Is there a standard order in which heders should be
included?


One of the many things I learned in this newsgroup is that there is a
slight advantage to including your own headers first and any standard
library headers later. Reason: your own header ought to have included any
libraries they use already. Otherwise they will only work in a certain
include order which, as Victor says, is a Bad Thing.

I don't think it's a big deal, but putting your own headers first is a
modest sort of software test, and software can't be tested too much.


Thanks for this. One thing I try to do is to avoid #including header files
from within other header files. This means that I don't write header files
that rely on header files for other classes that I write. Where necessary,
I include forward declarations in my headers. Eg, I might have a header
like this:-

class My_Class; // Forward declaration
class Another_Class
{
public:
void foo(My_Class* bar);
}

I believe that this kind forward declaration doesn't work with STL
templates
like <vector>.

Since I don't include headers in my header files, my approach is to
have a
standard set of library includes that I put in a file called
Library_Haeders.h. Every one of the source files in my project includes
Library_Headers.h.

I've remembered since my posting yesterday that I originally started using
this approach when I was using C++ Builder. With Borland's compiler its
necessary to organise headers in this way in order for precompiled headers
to work properly. I no longer use Borland, but I'm keeping the
'Library_Headers.h' approach for the moment.

I think that the pros and cons are:-

Pro:-

i) My #include files (except for 'Library_Headers.h' don't need to
#include other #include files
ii) As a result of the above, I can always tell when looking at a source
file what is #included. I don't need to look in other files to see what
they #include.

Con:

i) Since Library_Headers.h includes all of the library headers that are
used in my application, there are many places where more is included than
is really needed.

On balance, I think that the pros outweigh the cons. I regard
Library_Headers.h as, in effect, providing a language extension. The
STL elements it provides are available to all or my source files.

This doesn't seem to be affecting compile times seriously. In any case, if
I
did start getting compile time problems, having a standard set of library
includes might become necessary again in order to get pre-compiled headers
working.

Chris, IMHO this is truly a terrible idea. There is nothing wrong with
including headers within headers. But your Library_Headers.h is unduly
obscure (since a third party wouldn't be familiar with it) and forces a
complete recompile of all your source code whenever you change it. Worse
yet, if you decide to reuse your header in a different context years from
now you will have no idea what Library_Headers.h contained.

Writing out all the include files required by a given header is excellent
documentation and makes your code more maintainable and portable. I also
recommend the practice of explicitly including and standard library routines
you are using even if you know darned well that they are already included in
one of your own headers. Again, it's good documentation and won't break
if you decide to implement your header differently.

I agree with Cy, by making all the source files reference all the header,
just adding a single private member to a header will result in a complete
recompile!
I generally have a file

StdIncludes.h:
//Guard Header

//Global definitions:
#define PLATFORM M_WIN32

//STL Headers:
#include <string>
using std::string;
#include <list>
using std::list;
#include <vector>
using std::vector;

#include <stdlib.h>
#include <math.h>

#define PI 3.414.....f

//End Guard Header

which is referenced but all the .cpp and .h files BUT is unlikely to
change, ie contains none of my own headers!

Mike

As mentioned in my follow-up to Cy's post, this is very similar to my
Library_Headers.h. The main difference is that I use a single using
directive

using namespace std;

rather than several using statements. I don't suppose it makes a lot of
difference, but I can see that there is a case for having separate
statements.

 

[Michiel Salters]

I am currently revisiting the code of a C++ application and restructuring
the code where appropriate to make it consistent with the overall logical
design.

As part of this, I am looking at the way .cpp files #include headers. My
question is this: Is there a standard order in which heders should be
included?

I tend to #include STL headers first, and my own headers later, but I can't
really think of a logical justification for this.

Slightly faster IIRC, because your own headers may also use the STL, but
not the other way around.

However, there is one important exception. In the implementation (X.cpp),
include the corresponding header (X.h) first. This ensures that you didn't
miss any forward declarations in that header.

Regards,
Michiel Salters

 

[Paavo Helde]

(e-mail address removed) (Michiel Salters) wrote in

Slightly faster IIRC, because your own headers may also use the STL,
but not the other way around.

However, there is one important exception. In the implementation
(X.cpp), include the corresponding header (X.h) first. This ensures
that you didn't miss any forward declarations in that header.

Unfortunately, this approach goes bang with MSVC pecompiled header
support ;-( They assume that you include the precompiled header first in
each cpp file (and to be more nasty, they silently ignore any previous
includes). So there...

Paavo

 

[Chris Gordon-Smith]

(e-mail address removed) (Michiel Salters) wrote in


Unfortunately, this approach goes bang with MSVC pecompiled header
support ;-( They assume that you include the precompiled header first in
each cpp file (and to be more nasty, they silently ignore any previous
includes). So there...

Paavo

Borland C++ Builder does something similar. Nowadays I'm using gcc, which
compiles my project at a reasonable speed without using precompiled
headers.