Skip to main content

    Lesson • Advanced

    Building Modular Applications

    By the end of this lesson you'll be able to split a C++ program across multiple files — declarations in headers, definitions in source files — understand how translation units compile and link separately, organise code with namespaces, and recognise where C++20 modules are heading. This is how every real-world C++ codebase is built.

    What You'll Learn

    • Split declarations into headers (.h) and definitions into source files (.cpp)
    • Explain translation units and how the linker joins object files
    • Use namespaces to organise code and avoid name collisions
    • Protect headers with #pragma once or include guards
    • Spot and fix multiple-definition (ODR) and circular-include errors
    • Read a brief intro to C++20 modules: export module and import

    💡 Real-World Analogy

    A header file is a restaurant menu; a source file is the kitchen. The menu (.h) lists what you can order — the dish names and what comes with them — without revealing the recipes. The kitchen (.cpp) holds the actual recipes — how each dish is made. A customer (another file) only needs the menu to place an order; they never walk into the kitchen. This is why you #include a header to use something, but the recipe is compiled just once in its own .cpp. Swap the kitchen's recipe and every customer still orders the same way — the menu didn't change.

    1. Headers vs Source Files: the WHAT and the HOW

    A real C++ program is rarely one file. You split it into headers (.h) and source files (.cpp). A header holds declarations — a function's name and the types it takes, written as a single line ending in a semicolon (int add(int a, int b);). It tells the compiler what exists. The source file holds the definition — the actual body in { } braces — the how. Other files #include the header to learn what's available; only the matching .cpp compiles the body. Read this worked example — each block is labelled with the file it belongs in.

    Worked example: header + cpp + main in one runnable file

    Read the file labels, run it, and match the output to the comments.

    Try it Yourself »
    C++
    #include <iostream>
using namespace std;

// In a real project these three blocks live in THREE separate files.
// Here they are stitched into one file so it runs in the browser.

// ============================================================
// math_utils.h  — the HEADER: declarations only (the WHAT)
// ------------------------------------------------------------
// #pragma once            // stops this header being pasted in twice
// int add(int a, int b);  // a DECLARATION: name + types, no 
...

    Pro Tip: put only declarations in a header. A definition placed in a header gets compiled into every file that includes it, which bloats compile time and causes "multiple definition" errors at link time. The exceptions are templates and short inline functions, which must live in the header.

    Your turn. Below is a finished function definition. Write the matching declaration — the line that would sit in the header so other files can call it. It is just the first line of the definition, ending in a ; instead of { }.

    🎯 Your turn: write the declaration

    Turn the definition into a one-line header declaration.

    Try it Yourself »
    C++
    #include <iostream>
using namespace std;

int main() {
    // 🎯 YOUR TURN — a header declares a function; a .cpp defines it.
    // The definition below is finished. Write the matching DECLARATION
    // that would live in the header so other files can call it.

    // 👉 Replace ___ with the declaration line (signature + a semicolon).
    //    Hint: it is the first line of the definition, ending in ; not {
    ___          // 👉 e.g.  int square(int n);

    // (Definition that would live in 
...

    2. Translation Units & Linking

    When you compile, each .cpp — plus everything its #includes pull in — becomes one translation unit. The compiler turns each translation unit into an object file (.o) completely on its own; it never sees the other .cpp files. Then the linker joins all the object files into one program, matching every function call to the single definition of that function. This is separate compilation, and it's the reason a one-line change rebuilds one file in a second instead of the whole project.

    Worked example: two translation units, joined by the linker

    See how each .cpp compiles alone and the linker matches the call to the definition.

    Try it Yourself »
    C++
    #include <iostream>
using namespace std;

// Each .cpp is a "translation unit": it is compiled on its OWN into
// an object file, and the LINKER joins those object files at the end.
//
// On a real machine you would type:
//   g++ -c geometry.cpp   ->  geometry.o   (one translation unit)
//   g++ -c main.cpp       ->  main.o       (another translation unit)
//   g++ geometry.o main.o ->  app          (the linker joins them)
//
// geometry.cpp never SEES main.cpp. They only meet at the linker,
//
...

    3. Namespaces — Organise Code & Avoid Collisions

    As a project grows, two modules will eventually want the same name — both a graphics and a physics module might define a Point. A namespace is a named box you wrap code in so those names don't clash. You reach into a namespace with the scope-resolution operator ::, as in graphics::Point. Namespaces are how the standard library keeps everything tidy under std::.

    Worked example: two modules, same name, no clash

    See how graphics::Point and physics::Point coexist.

    Try it Yourself »
    C++
    #include <iostream>
#include <string>
using namespace std;

// A namespace is a NAMED BOX around code. Two modules can both have a
// "Point" without clashing, because each Point lives in its own box.

namespace graphics {                 // box #1
    struct Point { double x, y; };   // a 2D point
    void draw(const Point& p) {
        cout << "Drawing at (" << p.x << ", " << p.y << ")" << endl;
    }
}

namespace physics {                  // box #2
    struct Point { double x, y, z; };  // a
...

    Common mistake: never put using namespace std; in a header. It silently pulls all of std into every file that includes the header, re-introducing exactly the name collisions namespaces exist to prevent. Inside a .cpp it's a convenience; in a header it's a trap. (The demos here use it only because they're single-file teaching examples.)

    Now you try. The greet() function below lives inside the bank namespace, so calling it bare won't find it. Qualify the call with the box name using ::.

    🎯 Your turn: qualify the namespace

    Call greet() through its bank:: namespace.

    Try it Yourself »
    C++
    #include <iostream>
#include <string>
using namespace std;

// A 'bank' module with a greet() function, wrapped in a namespace.
namespace bank {
    string greet() { return "Welcome to the bank"; }
}

int main() {
    // 🎯 YOUR TURN — greet() lives inside the 'bank' namespace, so a
    // bare greet() will NOT be found. Qualify it with the box name.

    // 👉 Replace ___ so it calls bank's greet()  (use  box::name )
    cout << ___ << endl;   // 👉 e.g.  bank::greet()

    // ✅ Expected output
...

    4. Putting It Together: a Small Multi-File App

    Here is the payoff. This little app is split into logger.h, app.h, and main.cpp. The benefits of this separation are concrete: faster builds (change logger.cpp and only it recompiles), clean APIs (a teammate using App reads only app.h, not its internals), independent testing (you can test Logger on its own), and reuse (drop logger.h into another project). Each block below is labelled with its file and the #include wiring is shown in comments.

    Worked example: a logger + app split across files

    See how app.h depends on logger.h and main.cpp wires them together.

    Try it Yourself »
    C++
    #include <iostream>
#include <string>
using namespace std;

// A small app split across files, stitched together here so it runs.
// Notice the includes are written in comments to show the wiring.

// ============================================================
// logger.h  (declaration — the public API)
// ------------------------------------------------------------
// #pragma once
// #include <string>
// class Logger {
// public:
//     explicit Logger(bool verbose);
//     void log(const std:
...

    5. A Peek Ahead: C++20 Modules

    C++20 introduced modules, a modern replacement for the #include system. Instead of pasting header text into every file, you write export module math; in a module-interface file and mark the public bits with export. Other files write import math; — no header, no include guards. Modules parse once (so builds are faster) and only exported names leak out (so APIs stay clean). Toolchain support is still uneven in 2026, so headers remain the portable default — but it's worth recognising the syntax.

    Read-only: export module / import syntax (with a runnable mirror)

    See module syntax in comments; the runnable part is plain C++ that mirrors it.

    Try it Yourself »
    C++
    // ============================================================
// C++20 MODULES — the modern alternative to headers.
// (Toolchain support is still uneven in 2026, so this is read-only.)
// ------------------------------------------------------------
// math.ixx  — a MODULE INTERFACE file
//
//   export module math;        // names this module "math"
//
//   export int add(int a, int b) {   // 'export' = visible to importers
//       return a + b;
//   }
//   int secret(int x) {              //
...

    🔎 Deep Dive: the One Definition Rule (ODR)

    The One Definition Rule says a function or variable may be declared as many times as you like, but defined exactly once across the whole program. Declarations are promises ("this exists somewhere"); the linker needs precisely one body to point each call at.

    Two failures break it. If a header has no include guard, including it twice in one .cpp defines its contents twice — the compiler errors with "redefinition". If you put a function body in a header that two .cpp files include, each translation unit gets its own copy and the linker errors with "multiple definition". The fix for the first is #pragma once; the fix for the second is to keep bodies in a .cpp.

    // greeting.h
#pragma once                 // ✅ header included twice? still processed once
int greet();                 // ✅ DECLARATION in the header — fine

// greeting.cpp
#include "greeting.h"
int greet() { return 42; }   // ✅ the ONE definition lives here

    Pro Tips

    • 💡 One header per public type: a class named Player belongs in Player.h / Player.cpp. Predictable file names make a codebase navigable.
    • 💡 Forward-declare to break dependencies: if you only use a Player* or Player&, write class Player; instead of #include "Player.h". Fewer includes means faster builds and fewer circular-include headaches.
    • 💡 Include guards on every header, always: add #pragma once as the first line of each header the moment you create it.
    • 💡 Keep using namespace out of headers: qualify names (std::string) in headers; save using for the top of a .cpp.

    Common Errors (and the fix)

    • "multiple definition of 'foo'" (ODR violation): you put a function body in a header that more than one .cpp includes, so each translation unit compiled its own copy. Move the body to a single .cpp and leave only the declaration in the header (or mark a small one inline).
    • "redefinition of 'struct Config'": a header was #included twice in the same file with no guard. Add #pragma once as the first line of the header, or wrap it in #ifndef CONFIG_H / #define CONFIG_H / #endif.
    • Circular includes (a.h includes b.h which includes a.h): the headers reference each other and never resolve. Break the loop with a forward declaration — replace one #include with class B; when you only need a pointer or reference to B.
    • "undefined reference to 'add(int, int)'" (linker error): you declared and called a function but never defined it — or you forgot to compile/link the .cpp that defines it. Provide the definition and pass every .cpp to the compiler.
    • "'Point' is ambiguous": two namespaces both define Point and you used it unqualified after using both. Qualify it explicitly: graphics::Point or physics::Point.

    📋 Quick Reference

    ConceptCode / RuleGoes in
    Declarationint add(int a, int b);.h header
    Definitionint add(int a, int b) { ... }.cpp source
    Include guard#pragma oncetop of every .h
    Use a header#include "math_utils.h".cpp that needs it
    Namespacenamespace bank { ... }.h or .cpp
    Qualify a namebank::greet()call site
    Break a cycleclass Player;forward declaration
    Module (C++20)export module math; / import math;.ixx / .cppm

    Frequently Asked Questions

    Q: Why split code into .h and .cpp files at all — can't I keep everything in one file?

    You can for a tiny program, but as projects grow it becomes painful. Splitting lets each .cpp compile on its own (so a one-line change rebuilds one file, not the whole project), lets several people work on different files, and lets you share a header as a clean public API without revealing the implementation. Separate compilation is the reason large C++ projects build in seconds after a small edit.

    Q: What exactly goes in the header and what goes in the .cpp?

    The header (.h) holds declarations — function signatures, class definitions, and constants — the WHAT. The .cpp holds definitions — the actual function and method bodies — the HOW. Other files #include the header to learn what exists; only the matching .cpp compiles the bodies. Keep definitions out of headers (except templates and inline functions) to avoid multiple-definition errors.

    Q: What is a translation unit?

    A translation unit is one .cpp file plus everything its #includes pull in, compiled together into a single object (.o) file. The compiler handles each translation unit independently and never sees the others. The linker then joins all the object files, matching each function call to the one definition of that function across the whole program.

    Q: Do I still need include guards if I use #pragma once?

    No — they do the same job, so pick one per header. #pragma once is a single line and is supported by every mainstream compiler. Traditional guards (#ifndef / #define / #endif) are 100% portable and work even on exotic toolchains. Most modern codebases just use #pragma once; the important thing is that every header has one or the other.

    Q: Are C++20 modules a replacement for headers I should use right now?

    Modules are the modern direction and fix real header pain (no textual #include, no include guards, much faster builds, and symbols only leak if you export them). But toolchain and build-system support is still uneven across compilers in 2026, so most teams keep using headers for portability. Learn how headers work first — you will read header-based code for years — and reach for modules once your compiler and build system fully support them.

    Mini-Challenge: a Temperature Module

    No blanks this time — just a brief and an outline. Build a tiny weather module with a conversion function, then call it through its namespace. This mirrors exactly how you'd carve a real feature into its own header and source file.

    🎯 Mini-Challenge: build a weather namespace

    Wrap a function in a namespace and call it with weather::.

    Try it Yourself »
    C++
    #include <iostream>
#include <string>
using namespace std;

int main() {
    // 🎯 MINI-CHALLENGE: a tiny "temperature" module
    //
    // Imagine you are building temperature.h / temperature.cpp.
    // In THIS single file, do all three steps:
    //
    // 1. Make a namespace called  weather  (your "module box").
    // 2. Inside it, write a function:
    //       double toFahrenheit(double celsius)
    //    that returns  celsius * 9.0 / 5.0 + 32.0
    // 3. In main(), call it as  weather::
...

    🎉 Lesson Complete

    • ✅ Headers (.h) hold declarations — the WHAT; source files (.cpp) hold definitions — the HOW
    • ✅ Each .cpp is a translation unit compiled alone; the linker joins the object files
    • ✅ Separate compilation means faster builds, clean APIs, independent testing, and reuse
    • ✅ Namespaces wrap code in named boxes; reach in with :: to avoid name collisions
    • ✅ #pragma once stops double inclusion; the ODR demands exactly one definition per program
    • ✅ C++20 modules (export module / import) are the modern, faster successor to headers
    • ✅ Next lesson: ABI & Linking — what really happens when object files are joined

    Sign up for free to track which lessons you've completed and get learning reminders.

    Previous

    Cookie & Privacy Settings

    We use cookies to improve your experience, analyze traffic, and show personalized ads. You can manage your preferences below.

    By clicking "Accept All", you consent to our use of cookies for analytics and personalized advertising. You can customize your preferences or reject non-essential cookies.

    Privacy Policy • Terms of Service