How do you organise your STL headers?

Question

I am working on a large project that uses the STL and have a question about your preferred way to organise your STL #includes.

• Do you prefer to #include each header in the source file it is used. For example, if both foo.cpp and bar.cpp require std::string, then both will #include <string>.
• Do you prefer to have a single header file that includes all the STL headers your project uses (i.e. add them to the MS 'stdafx.h' pre-compiled header).

The advantage of the first method is that the .cpp file is an independent unit and can be used in a different project without having to worry that you're missing a #include. The advantages of the second method is that you can take use your compilers pre-compiled header support plus you can wrap STL #includes in pragmas that disable some warnings (for example, some Boost headers will cause warnings when compiling at level 4).

Which do you prefer to use?

Answer 1

I only include the header files that are really needed in every source, and not 'catch all' headers, to keep dependencies (and hence compile times) as low as possible.

Precompiled headers can work irrespective of this (i.e. I rely on precompiled headers to speed up the compiling process, not to get declarations). So even if something gets declared via the included precompiled headers, I still include the 'regular' header, which will get skipped by the include guard mechanism and won't add anything significant to the compile times.

As precompiled headers are a compiler specific thing. Optimizing / changing precompiled headers should have no effect on the correct functioning of the code in my opinion.

The main advantage of having dependencies as low as possible is that refactoring gets easier (or rather: feasible)

Great book on all this is Large Scale C++ Design from Lakos

Answer 2

Totally agree with the suggestion for John Lakos's book Large Scale C++ Design.

Declare all headers needed for a file, whether .h or .cpp, in the file itself. Don't rely on side effects of files included by other header files.

Having a large header file listing all includes increases dependencies unnecessarily and makes the design very brittle.

Oh, one other thing never have using declarations in a header file. Only ever use them in your implementation files, .cpp files.

HTH.

cheers,

Rob

Answer 3

What I do is include all STL headers I'm going to need in the entire project in my single precompiled header, usually the default StdAfx.h. A precompiled header is the de-facto first thing to set up in a project, including all STL-/boost-/platform headers and third party libraries.

STL & boost are neatly arranged in namespaces, so they don't ever cause any mix-ups or overlaps either.

In headers I usually use the full names, but in the source files do using namespace x when appropriate.

Answer 4

You can combine these two methods:

Have both .cpp - files include , and also add it to stdafx.h. This will still give you the PCH optimization.

The .cpp - file still needs to #include "stdafx.h", so its independence is debatable. However, the dependency is state explicitely, and removing the stdafx.h include is simpler than finding all the missing includes. Also, standard headers - as all headers should - make sure they are not included twice.

---

Generally, I agree with your approach to make each file "independent", i.e. when the .cpp is added to another project, or a .h is included, it takes care of its dependencies.

---

Remember that a PCH is a tradeoff, they can get huge. Having to much mostly unused code in the PCH can actually slow your builds down. Fast disks help a lot, though :)

Also be aware, that enabling precompiled headers in MSVC at least in some versions actually does change processing: declarations before the #include "stdafx.h" are ignored, so this needs to be your first non-comment statement. Ugly pitfall.