Header Files, Includes and the Preprocessor in C++

Trace the state

1. A caller includes add.h to know the declaration.
2. add.cpp contains the single definition.
3. The linker connects call sites to that definition.
4. Repeated includes are harmless because the guard prevents duplicate declarations within one translation unit.

Boundary task

For the bad header exercise, label which lines belong in the header, which belong in the source file and which should be removed.

Image loader split

The header announces the API; the source file implements it.

// image_loader.h
#pragma once
#include <string>
struct Image;
Image load_image(const std::string& path);

// image_loader.cpp
#include "image_loader.h"
Image load_image(const std::string& path) {
    // load bytes and build Image
    return Image{};
}

Applied task

Look at a header and mark each line as interface, implementation or avoidable dependency.

Traditional guard

The macro ensures the declarations appear once per translation unit.

#ifndef MATH_ADD_H
#define MATH_ADD_H

int add(int a, int b);

#endif

Pragma once

A common modern alternative.

#pragma once
int add(int a, int b);

Applied task

Choose one guard style for a small project and explain the consistency benefit.

Project and library includes

Use the form that communicates where the declaration lives.

#include "photo_loader.h"
#include <vector>
#include <string>

Applied task

Explain why a project header should not look like a standard library header.

Two module interfaces

The analyser can include only what it needs.

// photo_loader.h
#pragma once
#include <string>
struct Photo;
Photo load_photo(const std::string& path);

// photo_analyser.h
#pragma once
struct Photo;
double brightness_score(const Photo& photo);

// photo_analyser.cpp
#include "photo_analyser.h"
#include "photo_loader.h"
double brightness_score(const Photo& photo) { return 0.0; }

Applied task

Decide which header a file needs if it only stores a pointer or reference to Photo.

Forward declare for references

The full Image definition can live in a source file if the header only uses a reference.

class Image;
void process(Image& image);

Applied task

Identify which declarations require a complete type and which can use a forward declaration.

Bad global in a header

Every includer defines x, so the linker sees duplicates.

// bad.h
int x = 42; // wrong in a header

Extern plus single definition

Declare in the header, define once in a .cpp.

// good.h
#pragma once
extern int x;

// good.cpp
#include "good.h"
int x = 42;

Header-only template

Template definitions are commonly kept in headers.

template <typename T>
T add(T a, T b) {
    return a + b;
}

Applied task

For a header that defines globals, decide whether each item should become extern, inline constexpr, a function, or a source-file detail.

Case 1: The duplicate symbol

A header defines int counter = 0; and is included by two source files. Explain the multiple-definition error and repair it.

Case 2: The include cycle

A.h includes B.h and B.h includes A.h. Decide where a forward declaration is sufficient.

Case 3: Header pollution

A header uses using namespace std;. Explain how that affects every includer and remove it.

A. Move a definition out of the header

This header will define add in every includer.

// bad_math.h
#pragma once
int add(int a, int b) { return a + b; }

// a.cpp
#include "bad_math.h"

// b.cpp
#include "bad_math.h"

• Keep the declaration in the header.
• Move the definition to math.cpp.
• Explain why the linker error disappears.

// math.h
#pragma once
int add(int a, int b);

// math.cpp
#include "math.h"
int add(int a, int b) { return a + b; }

B. Clean a header

Remove namespace pollution and unnecessary includes.

// report.h
#pragma once
#include <iostream>
using namespace std;
void print_report(const string& title);

• Replace broad namespace use with qualified names.
• Include only the declaration dependencies.

// report.h
#pragma once
#include <string>
void print_report(const std::string& title);

C. Break a cycle

A pointer or reference can often use a forward declaration.

// A.h
#include "B.h"
class A { B* b; };

// B.h
#include "A.h"
class B { A* a; };

• Use forward declarations.
• Move includes into .cpp files where full definitions are needed.

// A.h
#pragma once
class B;
class A { B* b; };

// B.h
#pragma once
class A;
class B { A* a; };