Is there any material about how to use #include
correctly?
I didn't find any C/C++ text book that explains this usage in detail.
In formal project, I always get confused in dealing with it.

- 15,657
- 5
- 63
- 75

- 29,070
- 19
- 57
- 70
11 Answers
The big one that always tripped me up was this:
This searches in the header path:
#include <stdio.h>
This searches in your local directory:
#include "myfile.h"
Second thing you should do with EVERY header is this:
myfilename.h:
#ifndef MYFILENAME_H
#define MYFILENAME_H
//put code here
#endif
This pattern means that you cannot fall over on redefining the headers in your compilation (Cheers to orsogufo for pointing out to me this is called an "include guard"). Do some reading on how the C compiler actually compiles the files (before linking) because that will make the world of #define and #include make a whole lot of sense to you, the C compiler when it comes to parsing text isn't very intelligent. (The C compiler itself however is another matter)

- 28,526
- 15
- 68
- 103
-
2The pattern is called "include guard". – Paolo Tedesco Jan 21 '09 at 09:35
-
5And most compilers allow the `#pragma once` equivalent – xtofl Jan 21 '09 at 10:34
-
3@xtofi: No they don't. That is a MS extension. Very few other compilers support it. – Martin York Jan 21 '09 at 12:38
-
5@Spence: No that is not correct. The second include also searches a set of directories (just a different set) – Martin York Jan 21 '09 at 12:41
-
1@Martin: Indeed - it's only MS and gcc support #pragma once (and the latter doesn't officially). It seems especially hard to define the concept of 'the same file' in a rigorous way. Why don't we have an equivalent to the php "include" vs "require"? – xtofl Jan 21 '09 at 12:56
-
@xtofl: I agree it would be nice feature. But even the php stuff fails for the same reason: http://us2.php.net/require – Martin York Jan 21 '09 at 13:16
-
1the _H and uppercase are kinda important too. Once when I had less experience I used the include guard with the same name and case as the class definition in the file.. it kinda drove me batty for a while that it wouldn't compile. – Dan Jan 21 '09 at 17:54
-
3Martin is right. the difference between "" and <> is not certain. it's implementation defined what that difference is. most compilers, however, will make look into the file-relative path first when "" is used. – Johannes Schaub - litb Jan 21 '09 at 22:20
- Check Large-Scale C++ Software Design from John Lakos if you have the money.
- Google C++ coding guidelines also have some OK stuff.
- Check Sutter Herb materials online (blog) as well.
Basically you need to understand where include headers are NOT required, eg. forward declaration. Also try to make sure that include files compiles one by one, and only put #includes in h files when it's a must (eg. templates).

- 730,956
- 141
- 904
- 1,278
-
I think what you talked about is what I need.Stuff above are easy enough so that everyone knows it. – MainID Jan 21 '09 at 10:06
So your compiler may support 2 unique search paths for include files:
Informally we could call the system include path and the user include path.
The #include <XX> searches the system include path.
The #include "XX" searches the user include path then the system include path.
Checking the draft standard n2521:
Section 16.2:
2 A preprocessing directive of the form
# include < h-char-sequence> new-line
searches a sequence of implementation-defined places for a header identified
uniquely by the specified sequence between the < and > delimiters, and
causes the replacement of that directive by the entire contents of the
header. How the places are specified or the header identified is
implementation-defined.
3 A preprocessing directive of the form
# include " q-char-sequence" new-line
causes the replacement of that directive by the entire contents of the
source file identified by the specified sequence between the " " delimiters.
The named source file is searched for in an implementation-defined manner.
If this search is not supported, or if the search fails, the directive is
reprocessed as if it read
# include < h-char-sequence> new-line
with the identical contained sequence (including > characters, if any)
from the original directive.
An example of this would by gcc
-isystem <dir> Add <dir> to the start of the system include path
-idirafter <dir> Add <dir> to the end of the system include path
-iwithprefix <dir> Add <dir> to the end of the system include path
-iquote <dir> Add <dir> to the end of the quote include path
-iwithprefixbefore <dir> Add <dir> to the end of the main include path
-I <dir> Add <dir> to the end of the main include path
To see where your gcc is searching do this:
g++ -v -E -xc++ /dev/null -I LOOK_IN_HERE
#include "..." search starts here:
#include <...> search starts here:
LOOK_IN_HERE
/usr/include/c++/4.0.0
/usr/include/c++/4.0.0/i686-apple-darwin9
/usr/include/c++/4.0.0/backward
/usr/local/include
/usr/lib/gcc/i686-apple-darwin9/4.0.1/include
/usr/include
/System/Library/Frameworks (framework directory)
/Library/Frameworks (framework directory)
End of search list.
So how do you use this knowledge.
There are several school of thought. But I always list my libraries from most specific to most general.
Example
File: plop.cpp
#include "plop.h"
#include "plop-used-class.h"
/// C Header Files
#include <stdio.h> // I know bad example but I drew a blank
/// C++ Header files
#include <vector>
#include <memory>
This way if the header file "plop-used-class.h" should have included <vector> this will be cought by the compiler. If I had put the <vector> at the top this error would have been hidden from the compiler.

- 257,169
- 86
- 333
- 562
-
... which compilers support the *system path vs. user path* distinction? It seems you are solely referring GCC here ... – Wolf Dec 12 '17 at 14:48
-
1@Wolf I quoted the standard (As it was back in 09). Which says how the file is found is `implementation-defined`. I then show how gcc implementation as an "example" (gcc is the dominant c++ compiler at the time, clang is around but is barely usable back in 09 not relavant until 2011, MS cl compiler only seems to have a single search path). – Martin York Dec 12 '17 at 17:05
-
I see, thanks. So you translated *implementation-defined places* into *system include path*. – Wolf Dec 12 '17 at 17:12
-
@Wolf In addition to answering the question exactly with a quote from the standard. I then illustrated a real world example of how an implementation interpreted `implementation-defined` to solve a real world situation. – Martin York Dec 12 '17 at 18:56
In addition to the other comments, remember that you don't need to #include a header in another header if you only have a pointer or reference. E.g.:
Header required:
#include "Y.h"
class X
{
Y y; // need header for Y
};
Header not required:
class Y;
class X
{
Y* y; // don't need header for Y
};
//#include "Y.h" in .cpp file
The second example compiles faster and has less dependencies. This can be important in large code bases.

- 2,297
- 1
- 21
- 28
-
-
Yup, that's a forward declaration. Very useful for speeding up compilation. It only works when the compiler doesn't need details; you can't use it for base classes, actual members, that sort of thing. – David Thornley Jan 21 '09 at 22:05
Just an addendum to Andy Brice's answer, you can also make do with forward declarations for function return values:
class Question;
class Answer;
class UniversityChallenge
{
...
Answer AskQuestion( Question* );
...
};
Here's a link to a question I asked a while back with some good answers http://bytes.com/groups/c/606466-forward-declaration-allowed.

- 8,327
- 9
- 52
- 63
Header files are C's way of separating interface and implementation. They are divided into two types: standard and user-defined header files. A standard header file, such as string.h, allows us access to the functionality of an underlying C library. You should #include it in every .c file which uses the relevant functionality. Usually this uses brackets as in #include A user-defined header file exposes your implementation of functions to other programmers or other parts of your C code. If you have implemented a module called rational.c for calculations with rational numbers, it should have a corresponding rational.h file for its public interface. Every file which uses the functionality should #include rational.h, and also rational.c should #include it. Usually this is done using #include "rational.h" The part of compilation which does the #includes is called the C preprocessor. It mostly does text substitutions and pastes text. Spence is correct in his pattern for preventing duplicate #includes, which mess up the namespace. This is the base of inclusion, GNU Make gives you lots more power, and lots more trouble as well.

- 20,565
- 5
- 44
- 69
Check out the discussion on using #include<filename.h>
and #include<filename>
for C++ includes of C libraries.
Edit: Andy Brice also made this point in a briefer way.
Following up in null's answer, the most important thing to think about is where you put your #include's.
When you write a #include the preprocessor literally includes the contents of the file you list in the current file, including any #includes in those files as well. This can obviously lead to very large files at compile time (coad bloat), so you need to consider carefully if an #include is needed.
In a standard code file layout where you have a .h file for a class with the class and function declarations, and then a .cpp implementation file, you should be be careful of the number of #includes that go in the header file. This is because, every time you make a change to the header file, any files that also include it (that is, that use your class) will also have to be recompiled; if the header itself has lots of includes then every file that uses the class gets bloated significantly at compile time.
It is better to use forward declarations where possible, so that you can write the method signatures, etc. and then #include the relevant files in the .cpp file so that you can actually use the classes and structures that your code depends on.
//In myclass.h
class UtilClass; //Forward declaration of UtilClass - avoids having to #include untilclass.h here
class MyClass
{
MyClass();
~MyClass();
void DoSomethingWithUtils(UtilClass *util); //This will compile due to forward declaration above
};
//Then in the .cpp
#include utilclass.h
void MyClass::DoSomethingWithUtils(UtilClass *util)
{
util->DoSomething(); //This will compile, because the class definition is included locally in this .cpp file.
}

- 30,738
- 21
- 105
- 131

- 7,440
- 8
- 43
- 65
-
*This will compile, because [...]* <-- I don't think that this is a really helpful comment: it's a lot of work to say why code compiles. In your particular case, this is also **wrong**, because the compiler will probably stop already at `#include utilclass.h` ;) so you better have tried to really compile this before ... – Wolf Dec 13 '17 at 08:51
Is there any material about how to use #include correctly?
I'd strongly recommend section, SF: Source files, of the C++ Core Guidelines as a good starting point.
I didn't find any C/C++ text book that explains this usage in detail.
Much conventional wisdom on the topic of physical composition of C++ projects can likely be found in "Large-Scale C++ Software Design" by John Lakos.
In formal project, I always get confused in dealing with it.
You are in good company. Prior to C++20 modules, #include
was the only practical way to compose C++ translation units from multiple files. It is a simple, limited facility through which the preprocessor essentially copy/pastes entire files into other files. The resultant compiler input is often huge, and work is commonly repeated from one translation unit to the next.

- 5,528
- 4
- 34
- 38
First decide if you need it. From https://cplusplus.com/articles/Gw6AC542/
- do nothing if: A makes no references at all to B
- do nothing if: The only reference to B is in a friend declaration
- forward declare B if: A contains a B pointer or reference: B* myb;
- forward declare B if: one or more functions has a B object/pointer/reference as a parementer, or as a return type: B MyFunction(B myb);
- #include "b.h" if: B is a parent class of A
- #include "b.h" if: A contains a B object: B myb;

- 15,850
- 12
- 65
- 103
You use #include "yourfile.h"
if yourfile.h
is in the current working directory
and #include <yourfile.h>
if the path to yourfile.h
file was included in the C++ include directories (somewhere in configuration, example: c:\mylib\yourfile.h
, the path c:\mylib\
has to be specified as an include directory)
Also you can include .cpp and .hpp (h plus plus).
There is a particular set of files that can be written like: #include <iostream>
. For this to particular example work you need to specify using namespace std;
There is a very nice software that is integrated with microsoft's visual c++ , and shows the include paths. http://www.profactor.co.uk/includemanager.php

- 9,679
- 7
- 62
- 108
-
1*For this to particular example work you need to specify using namespace std;* <-- this makes not much sense here, better remove this advice. – Wolf Dec 13 '17 at 08:46