Should I Include Every Header

Should I include every header?

If you use a header related entity (e.g. some type) in a file, you should include the related header for it. Don't rely on headers to include each other. If you use it, include it.

The C++ standard library doesn't mandate inclusion of <string> in <vector> nor vice-versa. Trying to make use of functionality like this would limit the code to a specific implementation. In general, the standard library headers may or may not include other headers (or their own internal headers) in an unspecified order or manner. One notable exception is <initializer_list> which is required to be included in a few of the other standard headers. Changes to this unspecified order or manner can also happen, thus breaking previously compiling code with the updated compiler or an updated standard library implementation (this has been known to happen).

Also consider that if the header file is the definition for the class, then it should include what is required for the definition of that class. The associated .cpp should include its associated .h and the remaining files required to implement the class. Don't need it, don't include it; don't include more than needed (llvm style guide). One exception here is templates (that don't have an associated .cpp); this exception would apply to other header only implementations.

It is noted that maintenance of the include what you use can be difficult in the long run; thus it makes sense that it is important in the beginning of the coding cycle to include what is required for the interface; and then again to check the includes with any reasonable change that is made to the code.

There seems to be some progress w.r.t. tools in this regard, such as the iwyu project, that uses the clang tool chain and seems to have support for msvc as well.

One counter example would be if the reason for the header is to include other headers, then maybe, but even then I would be very careful - make sure it is clearly defined what it includes. An example of this could be a precompiled header.

Is it good practice to always include the standard headers?

Best practice is for each source file, whether it is a .c file or .h file, to include only the headers it needs. Doing so not only reduces compilation time but also serves to document the file's functionality.

Here are a few examples:

f1.c:

#include <stdio.h>

void print_int(int i)
{
    printf("i=%d\n", i);
}

f2.c:

#include <stdlib.h>

void *safe_malloc(size_t size)
{
    void *p = malloc(size); 
    if (!p) exit(1);
    return p;
}

f3.c:

int sum(int a, int b)
{
    return a+b;
}

The file f1.c only includes stdio.h because it does I/O but no other functions. Similarly, f2.c only includes stdlib.h because it uses functions defined there but does not use any I/O function, and f3.c doesn't include any headers because it doesn't need them.

If you think you've included unnecessary files, comment them out and compile with all warnings enabled to see which ones declare functions or variables you need.

Should I include in the main file the headers that are already included in the .h file?

Suppose main.c is a long file and uses both the standard library function signal and your routine foo. Also, main.c includes your header "foo.h", which includes <signal.h>. main.c does not itself include <signal.h>.

This will compile, since the compiler sees a declaration of signal while compiling main.c, because <signal.h> is included by way of "foo.h".

The next year, one of your coworkers reorganizes the software, and they move all of the code in main.c that uses foo out of main.c into bar.c. So they also move #include "foo.h" from main.c to bar.c. The other code in main.c that calls signal remains in main.c.

Now main.c will not compile, because it uses signal, but there is no include of <signal.h> in main.c, either directly or indirectly.

So, a habit of directly including in each source file a header file for each function (or other identifier) that the source file uses directly would avoid this issue.

However, it is a minor issue. The failure to compile will be noticed immediately and corrected promptly.

There can be other issues, such as an author might accidentally use a standard library function and forget to include the corresponding header, and the source code also contains a non-standard declaration of the same identifier. (It is easy not to remember the names of every identifier in the standard library and to use some of the simpler ones for other purposes.) Some compilers might warn about non-standard declarations that conflict with the standard library identifiers. However, your compiler does not, this situation can result in a buggy program, as the place where you intended to use a standard library function will instead use the alternate declaration. So always including a standard library header for the standard library functions you use can avoid this.

Is it right to simply include all header files?

Including unneeded header files is a very bad practice. The issue of slowing down compilation might or might not matter; the bigger issue is that it hides dependencies. The set of header files you include in a source file should is the documentation of what functionality the module depends upon, and unlike external documentation or comments, it is automatically checked for completeness by the compiler (failing to include needed header files will result in an error). Ensuring the absence of unwanted dependencies not only improves portability; it also helps you track down unneeded and potentially dangerous interactions, for instance cases where a module which should be purely computational or purely data structure management is accessing the filesystem.

These principles apply whether the headers are standard system headers or headers for modules within your own program or third-party libraries.

Is it a good idea to put all of your includes in one header file?

No. It simply adds cruft and overhead.

One of the biggest pains that you'll face as a maintainer is figuring out what headers don't need to be included and get rid of them. Whe you get to a list of 20+ headers, you start contemplating ugly things like brute forcing through it (removing one at a time and seeing if anything breaks).

Be kind to people who have to maintain your stuff in the future. Use the headers you need per module, no more .. no less :)

Do I need to include libraries in my main cpp, even if it's been included in a header file?

An include preprocessor directive tells the preprocessor to replace it with the contents of the file. Hence when you have

// some_header.h
#include <foo>

and

// some_source.cpp
#include <some_header.h>

then if you compile source.cpp, what the compiler gets to see after the preprocessing step is this:

// some_source.cpp
... contents of foo ...

That is: The #include <some_header.h> is replaced by contents of that header and #include <foo> is replaced by contents of foo.

No, you do not need to include headers twice. Though as headers should have include guards it also won't hurt. The recommonendation is: Include what you use (but not more).

Why not include all the standard headers always?

Besides

• namespace pollution
• compilation time (although reducable by precompiled headers, it will hurt those compiling a large project once because they actually want to use it, and not develop - also you want to think about rebuilds which are necessary once in a while)

you named "Less figuring out which headers I need and in which header a certain function is" as a benefit. I agree so far as this can be true for well designed libraries and headers.

In practice however I experienced (at least with MFC/ATL) some errors which could be solved by figuring out the correct order of includes. On the other hand one day you want to resolve an issue which makes you travel across the included headers - now imagine yourself looking at tons of headerfiles actually having nothing to do with your code file.

My conclusion is: The time you save by including a bunch of unnecessary headers do not pay off if you have to maintain a large project later on. The more time you invest before starting including any headers, the more time you will safe afterwards - but mostly without actually recognizing it.

Should I use a single header to include all static library headers?

In general, when linking the final executable, only the symbols and functions that are actually used by the program will be incorporated. You pay only for what you use. At least that's how the GCC toolchain appears to work for me. I can't speak for all toolchains.

If the client will always have to include the same set of header files, then it's okay to provide a "convience" header file that includes others. This is common practice in open-source libraries. If you decide to provide a convenience header, make it so that the client can also choose to include specifically what is needed.

To reduce compile times in large projects, it's common practice to include the least amount of headers as possible to make a unit compile.

---

Related Topics