Header Files

In a previous section, we saw how we could declare and define a function in two separate steps.

The declaration of a function uses its prototype. The prototype includes the function’s return type, its name, and the types of its parameters.

1// A function declaration
2int Add(int x, int y);

The definition includes all those things, but also includes the body of the function, where its behavior is implemented:

1// A function definition
2int Add(int x, int y) {
3  return x + y;
4}

We also introduced how we could do something similar with class functions. Let's imagine we have this class:

1class Character {
2  void TakeDamage(int Damage) {
3    // Implementation
4  };
5};

The above code could instead be written like this:

1// Character.cpp
2class Character {
3  void TakeDamage(int Damage);
4}
5
6void Character::TakeDamage(int Damage) {
7  // Implementation
8}

1class Maths {
2  int Add(int x, int y);
3}

1int Add(int x, int y) {
2  return x + y;
3}

1class Maths {
2  int Add(int x, int y) {
3    return x + y;
4  }
5};

1int Maths::Add(int x, int y) {
2  return x + y;
3}

This separation may have seemed like a niche quirk when first introduced. However, it is the most common way C++ code is written. This lesson will explain why.

Multiple Source Files

In our lesson on forward declarations, we introduced the distinction between declarations and definitions.

Forward Declarations

Understand what function prototypes are, and learn how we can use them to let us order our code any way we want.

Functions need to be declared before we use them, so we added a forward declaration, with the function being defined elsewhere. In that lesson, the function was defined later in the same file:

1void SomeFunction();
2
3int main() {
4  SomeFunction();
5}

In the previous lesson, we saw an alternative approach where the function could be defined in a different file entirely and then pasted into our main.cpp file using the #include directive:

1// utils.cpp
2int Add(int x, int y) {
3  return x + y;
4}

1// main.cpp
2#include "utils.cpp"
3
4int main() {
5  int result = Add(5, 3);
6}

In real-world projects, we use a combination of these two approaches. We organize our project into multiple source files as we covered in the previous lesson.

However, if one source file wants to use something that is defined in another source file, we simply forward declare it rather than including the entire source file:

1// utils.cpp 
2void PrintMessage() {
3  std::cout << "Hello World!";
4}

1// main.cpp
2void PrintMessage(); // Forward declaration
3
4int main() {
5  PrintMessage();
6}

Note for this to work, our compiler needs to be aware that our project now includes this additional source file. If we simply create a file in our file system, the compiler is not going to know that we want this file included in our project.

Instead, we typically want to add additional files through our IDE. In Visual Studio, we do this by opening the Project menu from the top menu bar, and selecting Add New Item (or Add Existing Item if we already created the file outside of Visual Studio)

Class Declarations

This scenario applies to classes too. Below, our Character class is referencing a Weapon class, which is defined elsewhere, so we need to forward declare it:

1// Forward Declaration
2class Sword;
3
4class Character {
5  Sword* mWeapon;
6};

With classes, the situation is often a little more complex. Any functions or variables on that class that we want to use need to be forward declared, too:

1class Sword {
2public:
3  void Equip();
4  void Unequip();
5  int GetDamage();
6};
7
8class Character {
9public:
10  void Equip(Sword* Weapon) {
11    mWeapon->Unequip();
12    mWeapon = Weapon;
13    mWeapon->Equip();
14  }
15
16  void Attack(){
17    int WeaponDamage{mWeapon->GetDamage()};
18    // ...
19  }
20
21 private:
22  Sword* mWeapon;
23};

Scattering forward declarations like this around our code base any time our class is used gets very messy.

So by convention, we instead declare our class in a single file, and then #include it wherever it is needed.

The file where we do this is called a header file.

Using Header Files

By convention, we give our header files .h or .hpp extensions. Typically, each header file includes the declaration for only one class. So, for example, our Sword class would be declared in a file called Sword.h:

1// Sword.h
2#pragma once
3
4class Sword {
5public:
6  void Equip();
7  void Unequip();
8  int GetDamage();
9};

We then #include the file wherever it is needed. This applies to the source file, Sword.cpp, where we provide definitions for all these functions:

1// Sword.cpp
2#include "Sword.h"
3
4void Sword::Equip(){
5  // Implementation here
6}
7
8void Sword::Unequip(){
9  // Implementation here
10}
11
12int Sword::GetDamage(){
13  // Implementation here
14}

We also #include our Sword header within the header of any other class that needs it:

1// Character.h
2#pragma once
3#include "Sword.h"
4
5class Character {
6public:
7  void Equip(Sword* Weapon);
8  void Attack();
9
10 private:
11  Sword* mWeapon;
12};

1// Sword.h
2#pragma once
3
4class Sword {
5public:
6  void Equip();
7  void Unequip();
8  int GetDamage(){ return Damage };
9
10private:
11  int Damage{10;
12};

Why Not #include the Source File?

You might wonder why we don't just put everything in .cpp files and include those directly. After all, it would save us from creating separate header files. There are three important reasons why we use headers instead:

1. Compilation Speed: When you include a file, the compiler needs to process all of its contents. Headers typically contain just declarations, which are much faster to process than full implementations. Including source files would dramatically slow down compilation.
2. Code Organization: Headers serve as a "contract" or "interface" - they tell other developers what your class can do without showing how it does it. This makes it easier to understand and use your code.
3. Technical Requirements: Sometimes you have no choice. When two classes need to reference each other (like a Player holding a Weapon, and a Weapon knowing its Player), you need to separate declarations from definitions to avoid circular dependencies. We cover circular dependencies later in this lesson.

1// Character.h
2#pragma once
3
4class Character : public Actor {
5public:
6  virtual void FunctionA();
7
8private:
9  void FunctionB() override;
10};

1// Character.cpp
2#include "Character.h"
3
4// No specifiers are used in the definition
5void Character::FunctionA() {}
6
7void Character::FunctionB() {}

Linking

Let's imagine we have three files, set up like this:

1// main.cpp
2#include "Character.h"
3
4int main() {
5  Character Player;
6  Player.Greet();
7}

1// Character.h
2#pragma once
3
4class Character {
5 public:
6  void Greet();
7};

1// Character.cpp
2#include <iostream>
3#include "Character.h"
4
5using namespace std;
6
7void Character::Greet() {
8  cout << "Hi!";
9}

1Hi!

This code works, but it might not be entirely obvious why. Specifically, in main.cpp, why does Player.Greet() work?

The implementation of this function is never provided in main.cpp, even after the preprocessor runs.

The implementation is provided in Character.cpp, but none of our files have an #include directive that grabs the contents of Character.cpp.

However, even though main.cpp isn’t aware that Character.cpp exists, the compiler is aware. By paying attention to the compiler output, we can likely see it report exactly what it is doing:

1Compiling...
2main.cpp
3Character.cpp

The compiler is aware that there are two source files because, when we add and remove files from our project, our IDE keeps track of that. Every time we compile our project, our IDE sends that list to the compiler.

1<ItemGroup>
2  <ClCompile Include="Character.cpp" />
3  <ClCompile Include="main.cpp" />
4</ItemGroup>

The result of that process is that the compiler outputs two files - the result of compiling Character.cpp, and the result of compiling main.cpp. These are sometimes called object files and typically use an obj extension.

Once all of our object files are created, they’re sent to the linker to be combined into a cohesive package.

Within the main object file, the Character::Greet() function wasn’t available, so the compiler just left a temporary marker there. These markers are sometimes called external symbols.

They are instructions to the linker: "Character::Greet is probably in another object file - when you find it, link it here".

The linker scans through all our object files for these external symbols and resolves them with the correct connection.

If the definition cannot be found, the linker will throw an error. We can usually tell linker errors and compiler errors apart by their error code. Compiler errors typically are prefixed with C, whilst linker errors typically use LNK.

The following program creates a linker error simply by declaring a class function, but never defining it:

1class Monster {
2 public:
3  void Taunt();
4};
5
6int main() {
7  Monster Enemy;
8  Enemy.Taunt();
9}

From the output, we can see that main.cpp.obj was successfully created by the compiler. However, the linker was unable to find the external symbol Monster::Taunt() defined anywhere:

1main.cpp.obj : error LNK2019: unresolved
2external symbol "Monster::Taunt(void)"
3referenced in function main
4fatal error LNK1120: 1 unresolved externals

Incomplete Types

At the start of this lesson, we saw that we could forward declare a class with a simple class MyClass; statement:

1class Sword;
2
3class Character {
4  Sword* mWeapon;
5};

Our knowledge of header files doesn’t change this. We can still do this if we prefer - we don’t need to #include the full header file.

The header file includes declarations for all the class variables and functions. But in this case, the compiler doesn’t need to know all those details, it just needs to know that Sword is a class.

As such, we can reduce compilation times even further by not including header files unnecessarily.

When we use this, our class - Sword in this case - will be an incomplete type within the file we’re forward declaring it.

If we’re only referencing the class in scenarios like variable types and function return types/parameters, an incomplete type is sufficient:

1class Sword;
2
3class Character {
4public:
5  Sword* GetWeapon() { 
6    return mWeapon;
7  }
8
9  void SetWeapon(Sword* Weapon) { 
10    mWeapon = Weapon;
11  }
12
13private:
14  Sword* mWeapon; 
15};

If we need to access members of that type, we need to switch back to including the header:

1#include "Sword.h"; 
2
3class Character {
4 public:
5  int GetDamage() {
6    // This won't work with an incomplete type
7    return mWeapon->Damage;  
8  }
9
10 private:
11  Sword* mWeapon;
12};

Circular Dependencies in Header Files

Earlier, we saw where we sometimes need to forward declare a function to resolve circular dependencies.

This applies to header files, too. Below, Character requires Sword, and Sword requires Character

Having them #include each other's header files would create a circular dependency, and prevent either of them from being used:

1// Sword.h
2#pragma once
3#include "Character.h"
4
5class Sword {
6 public:
7  int Damage;
8  Character* Wielder;
9};

1// Character.h
2#pragma once
3#include "Sword.h"
4
5class Character {
6 public:
7  int GetDamage() { return Weapon->Damage; }
8  Sword* Weapon;
9};

We can break this by forward-declaring one (or both) of them instead:

1// Sword.h
2#pragma once
3class Character;
4
5class Sword {
6 public:
7  int Damage;
8  Character* Wielder;
9};

1// Character.h
2#pragma once
3class Sword;
4
5class Character {
6 public:
7  int GetDamage() { return Weapon->Damage; }
8  Sword* Weapon;
9};

This change has introduced an error in our GetDamage() function, as we can’t access the Damage variable through an incomplete type.

We could re-add the #include directive - we only needed to remove one of them to break the circular dependency.

However, that’s not always an option, and incomplete types are never an unsolvable problem in a header file anyway.

We can just move the definition to a source file, and import the full header there:

1// Character.h
2#pragma once
3class Sword;
4
5class Character {
6 public:
7  int GetDamage();
8  Sword* Weapon;
9};

1// Character.cpp
2#include "Character.h"
3#include "Sword.h"
4
5int Character::GetDamage(){
6  return Weapon->Damage;
7}

As with many things, the preference for header files vs forward declarations and incomplete types is mixed. Recommendations differ:

Either way, this technique is very common and we will see it a lot, particularly in graphics and game engines.

Summary

This lesson explores the use of header files and the linker. It emphasizes the standard practice of declaring classes in header files, while defining their functionalities in source files. The key learnings include:

• Review of function declarations and definitions, differentiating between the two with examples.
• Explanation of class functions, demonstrating separation of declaration in header files and definition in source files.
• Discussion on the use of header files in C++, including the conventions for .h or .hpp file extensions and the #pragma once directive.
• Insights into the linking process in C++, detailing how the linker combines object files and resolves external symbols.
• Exploration of forward declarations and incomplete types, highlighting their role in reducing compilation times and managing dependencies.

Preview

In the next chapter, we will delve into the concepts of Namespaces, Enums, and using statements in C++.

These lessons will explore how these features enhance code organization and readability, and prevent naming conflicts in larger projects.

We will also examine practical examples to demonstrate their application in real-world programming scenarios.

Key Topics to be Covered:

• Understanding and implementing Namespaces in C++ for organizing code and avoiding name conflicts.
• Detailed exploration of Enums (Enumerations) and their role in making code more readable and maintainable.
• Utilizing using statements effectively to simplify code and reduce verbosity, especially in the context of namespaces and enums.
• Practical examples demonstrating the use of Enums and using statements in various programming scenarios.
• Best practices and common pitfalls when using Namespaces, Enums, and using statements in C++ projects.

Next Lesson

Namespaces

Learn the essentials of using namespaces to organize your code and handle large projects with ease

ContinueView Course