Proper Including Style

[cppaddict]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires string. Is it
good form to repeat the <string> include to make the dependency
explicit, or do just allow the include to be make implicitly through
the .h include? That is, should the header of your .cpp file be:

#include "CustomClass.h"

OR:

#include <string>
#include "CustomClass.h"

thanks for any thoughts,
cpp

 

[Howard]

Just include it in your header file. There's no sense in including it
twice.

-Howard

"All programmers write perfect code.
....All other programmers write crap."

"I'm never wrong.
I thought I was wrong once,
but I was mistaken."

 

[Leor Zolman]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires string. Is it
good form to repeat the <string> include to make the dependency
explicit, or do just allow the include to be make implicitly through
the .h include? That is, should the header of your .cpp file be:

#include "CustomClass.h"

OR:

#include <string>
#include "CustomClass.h"

thanks for any thoughts,
cpp

I currently favor putting the appropriate #includes in each source file
that uses them. The cost (in terms of increased compilation time due to
possible loss of precompiled header caching, if any) should be minimal on
modern computers. Anyone can look at the source file out of context and see
the facilities it directly uses (if there's an agreement on that style).

No one who sees those facilities being used would have to wonder whether
their headers are being properly included. This is a serious issue,
because some platforms' standard headers end up including other standard
headers (or the moral equivalent thereof), and others don't. A file might
compile fine on one platform even if a specific standard header is /never/
included, and this would cause the code to break when recompiled on a
platform that doesn't allow you to get away with that. This isn't the case
you've outlined above, specifically, but someone reading the code using
your first approach (everything included in the custom header, but not in
the file that includes it) wouldn't know that for sure unless they tracked
down all the headers.
-leor

 

[Joe Laughlin]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires
string. Is it good form to repeat the <string> include
to make the dependency explicit, or do just allow the
include to be make implicitly through the .h include?
That is, should the header of your .cpp file be:

#include "CustomClass.h"

OR:

#include <string>
#include "CustomClass.h"

thanks for any thoughts,
cpp

I generally put all the includes in the header files, and have the .cpp
files only include their corresponding .h files. Part of the reason is that
duplication is bad (if you have to add a header file, you have to add it to
two separate places).

 

[Mike Smith]

I currently favor putting the appropriate #includes in each source file
that uses them. The cost (in terms of increased compilation time due to
possible loss of precompiled header caching, if any) should be minimal on
modern computers. Anyone can look at the source file out of context and see
the facilities it directly uses (if there's an agreement on that style).

I agree. It's better to be clear than to be clever.

 

[Victor Bazarov]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires string. Is it
good form to repeat the <string> include to make the dependency
explicit, or do just allow the include to be make implicitly through
the .h include? That is, should the header of your .cpp file be:

#include "CustomClass.h"

OR:

#include <string>
#include "CustomClass.h"

The set of includes (which is usually located at the beginning of
the file) should contain _all_ necessary headers/files that the
current file needs.

Example (include guards in headers and some functionality are
omitted for simplicity):

----------------------------- A.h
class A {
// blah
};
----------------------------- B.h
#include "A.h"
class B {
A a;
void foo();
};
----------------------------- B.cpp
#include "B.h"
#include "A.h"
#include "somethingelse.h"

void B::foo() {
do_somethingelse(a);
}
----------------------------------

Now, that's what I'd do in B.cpp. Why? Imagine that somebody
relies on 'A.h' to be included in 'B.h' and doesn't include it
in 'B.cpp'. Later, somebody changes class B to acutally have
'a' to A*, and 'B.h' to have a forward-declaration of A instead
of including the header:

----------------------- new B.h
class A;
class B {
A* a;
};
--------------------------------

Now, the build process is broken because 'B.h' doesn't provide
the definition of class A any longer.

Yes, such a problem is usually pretty close on the surface and
you can probably find and fix it relatively easily. But what if
it's some kind of macro that if defined alters the way the code
compiles but doesn't produce an error if not defined?

Just my $0.02

Victor

 

[qWake]

I generally put all the includes in the header files, and have the .cpp
files only include their corresponding .h files. Part of the reason is that
duplication is bad (if you have to add a header file, you have to add it to
two separate places).

That approach has the following consequence: if your implementation changes
and requires a new header that is not already included in your .h file, you
have to change this .h file, which will force re-compilation of all other
dependent modules instead of just your .cpp file as it should. If you only
include in your .h file what this .h file directly needs, the problem does
not occur.

 

[E. Robert Tisdale]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires string.
Is it good form to repeat the <string> include
to make the dependency explicit?
Or just allow the include to be make implicitly through the .h include?
That is, should the header of your .cpp file be:

#include "CustomClass.h"
Yes.

OR:

#include <string>
#include "CustomClass.h"

No.

Your CustomClass.h header file
is your public *interface* to your CustomClass class.
If it requires the <string> header to be *self-sufficient*,
then it isn't necessary to include it again in your source file.

If, on the other hand, the <string> header is required only
by the *implementation of* and not the *interface to* your CustomClass,
you should include the <string> header *only* in your CustomClass.cpp
source file and *not* in your CustomClass.h header file.

 

[jeffc]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires string. Is it
good form to repeat the <string> include to make the dependency
explicit, or do just allow the include to be make implicitly through
the .h include? That is, should the header of your .cpp file be:

#include "CustomClass.h"

OR:

#include <string>
#include "CustomClass.h"

If the use of string is independent, it's best to include it again. For
example, if the use of string were for a parameter of a member function,
then of course you would definitely *not* want to use your second example.
That creates bad dependencies on the order of includes, etc. If it's
something used for implementation only, it should be included again. That
way if anything about the interface changes wrt needing the string
definition, then you only need remove it from the h file. It is also more
clear in terms of "self documentation".

 

[Phlip]

Say that your CustomClass.h header files requires

#include <string>

Now say that your CustomClass.cpp file also requires string. Is it
good form to repeat the <string> include to make the dependency
explicit, or do just allow the include to be make implicitly through
the .h include? That is, should the header of your .cpp file be:

#include "CustomClass.h"

OR:

#include <string>
#include "CustomClass.h"

thanks for any thoughts,

Per /Large Scale C++ Software Design/ by John Lakos, the first statement in
CustomClass.cpp should be #include "CustomClass.h". (Precompiled header
systems, like VC++'s "stdafx.h", may go above.)

If AnotherClass.cpp needs to use CustomClass, it should only need to include
its header. There should be no surprise dependencies. If CustomClass.h needs
std::string (likely), then #include <string> should be inside it.

But if CustomClass uses BigClass, it should try not to #include
"BigClass.h". It should instead forward declare what it needs like this:

class BigClass;
class CustomClass {
void method(BigClass & aBigClass);
...
};

Then, CustomClass.cpp will #include "BigClass.h". But any other class that
needs CustomClass but doesn't need BigClass won't #include "BigClass.h", and
won't see any of its identifiers. C++ has many scratchy parts, but it
matches logical to physical decoupling very well. One can partially
recompile small modules of large applications typically without accidentally
recompiling everything.

 

[E. Robert Tisdale]

I generally put all the includes in the header files, and have the .cpp
files only include their corresponding .h files. Part of the reason is
that

duplication is bad (if you have to add a header file, you have to add it
to

two separate places).

That approach has the following consequence:
if your implementation changes and requires a new header
that is not already included in your .h file,
you [must] change this .h file,
which will force re-compilation of all other dependent modules
instead of just your .cpp file as it should.

No.
If the .cpp source file requires a new header
that is not already included in your .h header file,
it should be included *only* in the .cpp source file.
If you need to include it in your .h header file as well,
it means that you must have changed the interface.

If you only include in your .h file what this .h file directly needs,
the problem does not occur.

Correct.

 

[Mike Smith]

I generally put all the includes in the header files, and have the .cpp
files only include their corresponding .h files. Part of the reason is that
duplication is bad (if you have to add a header file, you have to add it to
two separate places).

It's only necessary to add it twice if it's *used* in both the header
and the .CPP file. I could write a library that uses, say, std::string
in its *implementation*, but not as part of its *interface*; i.e. none
of the exposed functions accept or return std::string. In this case,
personally, I would #include <string> in the .CPP file, not in the header.