Best practice for including from include files

Question

I was wondering if there is some pro and contra having include statements directly in the include files as opposed to have them in the source file.

Personally I like to

Answer 1

I think second approach is a better one just because of following reason.

1. when you have a function template in your header file.

   class myclass
   {
       template<class T>
       void method(T& a)
       {
          ...
       }
   }
   

And you don't want to use it in the source file for myclass.cxx. But you want to use it in xyz.cxx, if you go with your first approach then you will end up in including all files that are required for myclass.cxx, which is of no use for xyz.cxx.

That is all what I think of now the difference. So I would say one should go with second approach as it makes your code each to maintain in future.

Answer 2

The language makes no requirements, but the almost universally accepted coding rule is that all headers must be self sufficient; a source file which consists of a single statement including the include should compile without errors. The usual way of verifying this is for the implementation file to include its header before anything else.

And the compiler only has to read each include once. If it can determine with certainty that it has already read the file, and on reading it, it detects the include guard pattern, it has no need to reread the file; it just checks if the controling preprocessor token is (still) defined. (There are configurations where it is impossible for the compiler to detect whether the included file is the same as an earlier included file. In which case, it does have to read the file again, and reparse it. Such cases are fairly rare, however.)

Answer 3

Having more (unwanted) includes in headers means having more number of (unwanted) symbols visible at the interface level. This may create a hell lot of havocs, might lead to symbol collisions and bloated interface

Answer 4

There's not really any standard best-practice, but for most accounts, you should include what you really need in the header, and forward-declare what you can.

If an implementation file needs something not required by the header explicitly, then that implementation file should include it itself.

Answer 5

A header file is supposed to be treated like an API. Let us say you are writing a library for a client, you will provide them a header file for including in their code, and a compiled binary library for linking.

In such scenario, adding a '#include' directive in your header file will create a lot of problems for your client as well as you, because now you will have to provide unnecessary header files just to get stuff compiling. Forward declaring as much as possible enables cleaner API. It also enables your client to implement their own functions over your header if they want.

If you are sure that your header is never going to be used outside your current project, then either way is not a problem. Compilation time is also not a problem if you are using include guards, which you should have been using anyway.

Answer 6

On the other hand, if I have the includes in the include files compile time might get bigger, because even with the include guards

If your compiler doesn't remember which files have include guards and avoid re-opening and re-tokenising the file then get a better compiler. Most modern compilers have been doing this for many years, so there's no cost to including the same file multiple times (as long as it has include guards). See e.g. http://gcc.gnu.org/onlinedocs/cpp/Once_002dOnly-Headers.html

Headers should be self-sufficient and include/declare what they need. Expecting users of your header to include its dependencies is bad practice and a great way to make users hate you.

If my_needed_file.h is needed before sample.h (because sample.h requires declarations/definitions from it) then it should be included in sample.h, no question. If it's not needed in sample.h and only needed in sample.c then only include it there, and my preference is to include it after sample.h, that way if sample.h is missing any headers it needs then you'll know about it sooner:

// sample.c
#include "sample.h"
#include "my_needed_file.h"
#include ...
#include <std_header>
// ...

If you use this #include order then it forces you to make sample.h self-sufficient, which ensures you don't cause problems and annoyances for other users of the header.