C++ is known for both its versatility and complexity. Part of the reason for its widespread usage is the fact that it is like an extension to the C programming language, inheriting much of C's syntax and semantics. That includes (non-intentional pun) the C preprocessor and the include system.

In this article I'm going to talk about how I include header files when I write C++, what conventions I use in order to maximize consistency and to avoid certain issues, and the rules I follow when I have to think about dependencies between source and header files. I hope that this will help you write better C++.

An Example Library

Let's start with an example of a C++ library that we might write, that uses a C library as a dependency, and it's being used by a C++ executable. We'll see all the code first, then I'll explain why I've written it this way throughout the article. We will refer to this code multiple times.

my_library.hpp

#pragma once

#include <cstddef>
#include <optional>
#include <filesystem>
#include <string>
#include <memory>

struct SomeCLibraryContext;

class MyLibrary {
public:
    explicit MyLibrary(std::size_t size);

    std::optional<int> return_optional_int() const;
    void take_filesystem_path(const std::filesystem::path& path);
private:
    std::size_t m_size;
    std::string m_string;
    std::shared_ptr<SomeCLibraryContext> m_some_c_library;
};

my_library.cpp

#include "my_library.hpp"

#include <some_c_library.h>

MyLibrary::MyLibrary(std::size_t size)
    : m_size(size), m_some_c_library(std::make_shared<SomeCLibraryContext>()) {}

std::optional<int> MyLibrary::return_optional_int() const {}

void MyLibrary::take_filesystem_path(const std::filesystem::path& path) {}

some_c_library.h

#ifndef SOME_C_LIBRARY_H
#define SOME_C_LIBRARY_H

typedef struct SomeCLibraryContext {} SomeCLibraryContext;

int some_c_library_initialize(SomeCLibraryContext* ctx);
int some_c_library_uninitialize(SomeCLibraryContext* ctx);
int some_c_library_do_thing(SomeCLibraryContext* ctx, int parameter);

#endif

some_c_library.c

#include "some_c_library.h"

int some_c_library_initialize(SomeCLibraryContext* ctx) {}
int some_c_library_uninitialize(SomeCLibraryContext* ctx) {}
int some_c_library_do_thing(SomeCLibraryContext* ctx, int parameter) {}

main.cpp

#include <my_library.hpp>

int main() {
    MyLibrary my_library {5};
    const std::optional<int> optional_int {my_library.return_optional_int()};
    const std::filesystem::path path {"/home/simon/Documents"};
    my_library.take_filesystem_path(path);
}

Let's say that we're writing MyLibrary. We don't actually care what it's doing. Instead, we care about what it contains and what it depends on as a class and as a C++ library. There are two kinds of dependencies in C++, that we are going to talk about: at the code level and at the binary level. Dependencies at the code level represent the relationships between the objects in the code, i.e. between types. Dependencies at the binary level are the relationships between C++ libraries and executables.

Code Level Dependencies

See that MyLibrary makes use of std::size_t, std::optional, std::filesystem::path etc. Those are all definitions that the class depends on. We have to include their corresponding header files in order to use them. Thus every single one of those includes brings in a dependency for the class. Remember the three relationship types between classes: composition, aggregation and association. std::string is a composite object, same as std::shared_ptr itself. For this matter we must include <string> and <memory>. std::optional and std::filesystem::path are associates. They are not part of the class, but they are used as function return types and parameters. For these too we must include <optional> and <filsystem>. Lastly, SomeCLibraryContext is an aggregate, because it's not a member of MyLibrary directly, it's a pointer instead. MyLibrary could work just fine with m_some_c_library being nullptr.

Take note that I did not include <some_c_library.h> in the header file for a reason. I instead wrote a forward declaration. MyLibrary is in fact very happy just knowing that SomeCLibraryContext exists somewhere, without knowing its full definition. I'll talk about the reason for this decision later, but now, looking at my_library.cpp, we finally include <some_c_library.h>, because here, in the implementation of MyLibrary, we do need the definition of SomeCLibraryContext and need to call its functions.

Binary Level Dependencies

.
├── CMakeLists.txt
├── main.cpp
├── my_library
│   ├── my_library.cpp
│   └── my_library.hpp
└── some_c_library
    ├── some_c_library.c
    └── some_c_library.h

CMakeLists.txt

cmake_minimum_required(VERSION 3.20)

project("how_to_include_header_files_in_cpp")

add_library(some_c_library STATIC "some_c_library/some_c_library.c" "some_c_library/some_c_library.h")
target_include_directories(some_c_library PUBLIC "some_c_library")

add_library(my_library STATIC "my_library/my_library.cpp" "my_library/my_library.hpp")
target_include_directories(my_library PUBLIC "my_library")
target_link_libraries(my_library PRIVATE some_c_library)

add_executable(main "main.cpp")
target_link_libraries(main PRIVATE my_library)

When I say binaries, I'm of course referring to executables and libraries. Libraries in C and C++ usually come with a compiled binary blob and a header file. Anywhere we include that header file, we bring in that library as a dependency (assuming we also link the library). Any time we include <string> or <iostream>, we bring in libstdc++, the standard library as a dependency. Including <some_c_library.h> in the source file of MyLibrary means that libmy_library alone depends on libsome_c_library. If we instead included <some_c_library.h> in the header file, then we just made libsome_c_library a dependency not only on libmy_library, but also on all of its dependents (all libraries and executables that depend on libmy_library). That is because including a header that includes other headers and other headers recursively ends up including everything. I avoided including the library header <some_c_library.h> in the header file to keep libsome_c_library like an implementation detail to main, otherwise any code that uses libmy_library, like main, depended directly, instead of indirectly on libsome_c_library.

If we didn't care for that side effect, then we could have made SomeCLibraryContext a composite, which would have saved us a heap allocation. Then we had to also mark target some_c_library accessible from target main:

# ...

add_library(my_library STATIC "my_library/my_library.cpp" "my_library/my_library.hpp")
target_include_directories(my_library PUBLIC "my_library")
target_link_libraries(my_library PUBLIC some_c_library)  # Note the `PUBLIC` here

# ...

Friends Aren't Hard Dependencies

If in a header file containing a class, we need a specific object name just to mark it as a friend, then we don't need its full definition:

class_a.hpp

#pragma once

// Don't need to include class_b.hpp
class B;

class A {
    friend class B;
};

class_b.hpp

#pragma once

class B {};

To Include Or Not To Include

In the first example we can see that main.cpp only ever includes <my_library.hpp>. That is because it only needs <my_library.hpp>! Even though we use std::optional and std::filesystem::path in main(), we don't have to include <optional> and <filesystem>, because those are already included im <my_library.hpp>. A rule of thumb is that if we only use std::optional and std::filesystem::path in the context of <my_library.hpp>, then we don't include the headers again, but if we use them independent of <my_library.hpp>, then we should include them, because if at any point in the future we get rid of <my_library.hpp>, we'll suddenly have compilation errors with undefined symbols.

main.cpp

#include <iostream>
#include <cstdlib>

// Include these
#include <optional>
#include <string_view>

// some_dependency.hpp also includes <optional> and <string_view>, but we should not rely on that
#include "some_dependency.hpp"

static std::optional<std::string_view> get_env(const char* variable) {
    const char* value {std::getenv(variable)};
    if (value == nullptr) {
        return std::nullopt;
    }
    return std::make_optional(value);
}

int main() {
    DataFile data {"whatever.txt"};
    data.get_next_data();

    std::cout << get_env("HOME").value_or("[empty]") << '\n';
}

some_dependency.hpp

#pragma once

#include <optional>
#include <string_view>

class DataFile {
public:
    explicit DataFile(std::string_view file_path) {}

    std::optional<int> get_next_data() {}
};

g++ -o main main.cpp

We have to be careful which headers we include in other headers, for example in our library's headers. Users of our library may not be happy having tons of symbols accessible within their code because of our messy library header. For example, avoid including <cassert> or <iostream> in header files.

What do I hear? You say that you need to overload the << operator in order to print stuff? For that we may consider including <iosfwd> instead:

thing.hpp

#pragma once

#include <iosfwd>  // Don't include iostream here

struct Thing {
    int foo {};
};

template<typename CharType, typename Traits>
std::basic_ostream<CharType, Traits>& operator<<(std::basic_ostream<CharType, Traits>& stream, const Thing& thing) {
    stream << "Thing { " << thing.foo << " }";
    return stream;
}

main.cpp

#include <iostream>

#include "thing.hpp"

int main() {
    Thing thing;
    std::cout << thing << "\n";  // Printing works, because we included iostream, as we should
}

g++ -o main main.cpp

Here, we are making Thing printable to any sort of output stream. Because the function is a template, we can actually get away with writing its definition in the header, even though std::basic_ostream<...> is just a forward declaration. The header on its own compiles just fine. The moment we actually call operator<< on a Thing object we actually need <iostream> to be included. It just works!

Source/Header Pairs

Taking again a look at my_library.cpp in the first example, we see that the first line is #include "my_library.hpp". A rule of thumb here is when we have a pair of files something.hpp/something.cpp, the first line in something.cpp should always be an include of its header. That is because the header should be a self-contained section of the code and being pasted at the top of the source file ensures that we do make it self-contained. Take a look at this broken code now:

broken.hpp

#pragma once

struct Broken {
    void do_thing(std::string_view parameter);
};

broken.cpp

#include <string_view>

#include "broken.hpp"

void Broken::do_thing(std::string_view parameter) {}

broken_main.cpp

#include <string_view>

#include "broken.hpp"

int main() {
    Broken broken;
    const std::string_view str {"???"};
    broken.do_thing(str);
}

g++ -o broken_main broken_main.cpp broken.cpp

This code compiles just fine. But can you see the problem? broken.hpp is not self-contained. We include "broken.hpp" in broken.cpp after we include <string_view>, that shouldn't be there in the first place. And in broken_main.cpp we again somehow include <string_view> and the whole thing works, but it's messed up. Don't do that.

Also any header we include in something.hpp we should not include in something.cpp! something.hpp should include headers for both itself and something.cpp. And something.cpp then should include headers only for itself.

Angle Brackets Versus Quotes

In the last example, we included "broken.hpp" with quotes. That is because it's not a separate library. Library headers should be included with angle brackets and local headers in the current project should be included with quotes. The only difference between the two is that including with angle brackets searches the header only in system library directories and additional include directories, while including with quotes searches the header also in the current working directory of the file we are including into.

Order Of Inclusion

To keep the includes nicely organized, I like to have them in a specific order. That is:

something.cpp

#include "something.hpp"  // The source's header

#include <iostream>  // Standard library headers
#include <algorithm>
#include <cassert>

#include <some_library.hpp>  // Other library headers
#include <third_party_library.hpp>

#include "some_class_related_to_something.hpp"  // Project headers
#include "some_definitions_related_to_something.hpp"

Pay close attention to when we use quotes and when we use angle brackets.

Some people like to swap the standard library headers with project headers. I personally don't like that, but it's up to you. Also some people order those headers from each group alphabetically or in some other fashion. I don't mind it that much, but it's fine.

Conclusion

Now you've learned how to include stuff in your code! The key takeaway from this article is to be cautious about which headers you include and whether you actually need to include them or not, especially in other header files. Follow standard best practices like the ones presented earlier. And when refactoring C++ code, when shuffling code around... I wish you luck! Be careful not to end up with unnecessary, wrong or missing includes. That is indeed one of the hardest parts of C and C++.

I hope that you found this article useful!