Header Files

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

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.

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

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)

This scenario applies to classes too. Below, our Character class is referencing a Sword class. Sword 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 declaration is called a header file.

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};

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 which Player is holding it), you need to separate declarations from definitions to avoid circular dependencies. We cover circular dependencies later in this lesson.

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 knows 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 of files to the compiler.

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

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};

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 removing the #include directives and instead forward-declaring them as classes:

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 breaks the circular dependency, but has introduced an error in our GetDamage() function. Within Character.h, Sword is now an incomplete type, meaning we can't access the Damage variable of Sword objects. With an incomplete type, the compiler knows that Sword is a class, but it doesn't know what functions and variables that type has.

In this case, we could solve the problem by re-adding the #include "Sword.h" directive - we only needed to remove one of the includes to break the circular dependency.

However, that's not always an option. More generally, we can always solve problems like this by moving the function definitions that don't work with an incomplete type into a source (.cpp) file, and include the required 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:

Avoid using forward declarations where possible. Instead, include the headers you need.

Forward declarations are preferred to including headers.

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

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.