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.

Class Declarations

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:

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

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?

It seems our original problem could just have been solved by bundling our class definition and declarations into a single file, like Sword.cpp, and #include that wherever it is needed.

So, why do we use header files at all? There are three main reasons:

1. Compilation Time

Any code we #include needs to be compiled. So, including more code means our compilation times go up. This may not seem like a problem now, but in complex projects, compilation can take multiple minutes, potentially hours, if not managed properly.

Longer compilation times make it quite painful to experiment and test ideas, so it’s something we should try to keep low.

2. Developer Experience

When a developer wants to get an overview of how a class works, they don’t care about low-level implementation details of every function. Typically, we just want an overview of what public methods a class has available. Having a standalone header file provides exactly that.

3. We often have no choice

Splitting our class into separate definitions and declarations is often required. In our initial lesson on forward declaration, we saw that it was sometimes necessary to forward-declare a function to resolve circular dependencies.

That situation applies to classes too, with much higher frequency. For example, we can imagine our Character needs to have a Sword, and the Sword needs to know which Character is wielding it. Scenarios like this are very common, and can only be resolved by separating definition from declaration.

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