Precompiled Headers Overview

There are advantages to using precompiled headers for your C++ projects, but there are also pitfalls to avoid when creating and using precompiled headers.

Advantages of Using Precompiled Headers

Creating and using precompiled headers can do two major things for you:

Can reduce the compilation time of C++ files
Can reduce the number of lines of code that the compiler must process (in some cases, by several orders of magnitude)

Pitfalls to Avoid

When used indiscriminately, precompiled headers can actually increase compilation time. Watch out for the following potential pitfalls:

Simple compilation units that refer to very few symbols may compile faster without precompiled headers. Having them use a precompiled header might result in slower compilation.
If a header that changes regularly is part of the precompiled header, the overhead of constantly recreating the precompiled header might offset any gains from using one.
For very large precompiled headers, the I/O involved in reading or updating the file might offset the gains of precompiled headers.

Some headers are not good candidates to include in a precompiled header. Use the following guidelines to determine whether a header should be precompiled.

Do not include the following types of headers in a precompiled header:

Any header that is not already properly guarded. That is, the header file does not contain preprocessor guards (using #define) that would ensure that it is *seen* only once by the compiler even if it is included multiple times.
A header that contains code that relies on certain macros that only a few compilation units define.
Any header that is undergoing frequent or regular changes.
Any header that contains any data. The compiler generates a message about headers that contain data and therefore cannot be part of a precompiled header.

Precompiled headers can hide incorrect code. For example, a .cpp file that fails to explicitly include a needed header might compile with no errors when using a precompiled header that includes the missing header file but fail when the precompiled header is disabled. It's a good idea to build without precompiled headers every once in a while to ensure that your source correctly includes all necessary headers.