C++ Beginner · Lesson 20 of 22

Header files and project structure

Declarations in .hpp, definitions in .cpp, include guards and folder layout.

Estimated time · 45–75 min

Learning goals

What you will understand

Explain header files and project structure in your own words
Use it in a small robotics example
Verify the result instead of assuming it worked

Understand the idea first

The mental model

A header (.hpp) declares what a module offers; the source file (.cpp) defines how. Every .cpp that uses the module includes the header. Put #pragma once at the top of each header so it is only processed once per file.

A common layout is include/<project>/ for public headers, src/ for sources and tests/ for tests. Include only what you use, and never define a non-inline function in a header, or the linker will report it twice.

Guided lesson

Work through these steps

1.
Read the header files and project structure example and identify what each line owns or changes.
2.
Create a small source file, compile with -std=c++17 and warnings enabled, and run it.
3.
Change one input, predict the result before running, then compare the output.
4.
Record one compiler or runtime error and explain the correction in your own words.

Worked example

Read it before you run it

mkdir -p robot_lib/include/robot robot_lib/src robot_lib/tests
# Create the conventional folder layout in one command.
cat > robot_lib/include/robot/limits.hpp <<'EOF'
# Start writing the header file; the text up to the EOF line goes into it.
#pragma once
# Include the header only once per translation unit.
namespace robot { double clamp(double v, double low, double high); }
# Declare the function; no body here.
EOF
# End of the header.
cat > robot_lib/src/limits.cpp <<'EOF'
# Start writing the source file.
#include "robot/limits.hpp"
# Include our own header first, so a mismatch is caught by the compiler.
double robot::clamp(double v, double low, double high) { return v < low ? low : (v > high ? high : v); }
# Define the function declared in the header.
EOF
# End of the source file.
g++ -std=c++17 -Irobot_lib/include -c robot_lib/src/limits.cpp
# Compile it; -I adds the folder searched for #include lines.

What the example is doing

1.Read declarations from right to left: identify each value's type, name, and initial value.
2.Follow the data through each expression before considering syntax shortcuts.
3.Compile with warnings enabled; a clean build is part of the result, not an optional polish step.

Watch it run · Build and run

See what this code does

The terminal types this lesson's practice solution and runs it. The scene shows the kind of robot behaviour that code drives. It plays by itself and loops.

Practice code

Now type it yourself

Copy the starter into practice.cpp and replace every TODO with your own code. Build and run it: g++ -std=c++17 -Wall -Wextra -Wpedantic practice.cpp -o practice -pthread && ./practice

#include <iostream>

// ---- limits.hpp (the header: declarations only) ----
namespace robot {
double clamp(double v, double low, double high);
}

// ---- main.cpp ----
int main() {
  std::cout << robot::clamp(12.0, 0.0, 10.0) << '\n';
  std::cout << robot::clamp(-3.0, 0.0, 10.0) << '\n';
  return 0;
}

// ---- limits.cpp (the source: definitions) ----
// TODO: define robot::clamp() here, outside main; the header only declared it

Expected output

10
0

Stuck? Show the full solution (try it yourself first)

#include <iostream>

// ---- limits.hpp (the header: declarations only) ----
namespace robot {
double clamp(double v, double low, double high);
}

// ---- main.cpp ----
int main() {
  std::cout << robot::clamp(12.0, 0.0, 10.0) << '\n';
  std::cout << robot::clamp(-3.0, 0.0, 10.0) << '\n';
  return 0;
}

// ---- limits.cpp (the source: definitions) ----
namespace robot {
double clamp(double v, double low, double high) {
  return v < low ? low : (v > high ? high : v);
}
}  // namespace robot

Expected result

How you know it worked

After adding the shown fragment to the guided exercise with its listed headers and surrounding program, the finished program builds with -Wall -Wextra -Wpedantic.
Changing the stated input produces the result you predicted.

Practical exercise

Apply the lesson

Split a Motor class into motor.hpp and motor.cpp, add #pragma once, and use it from main.cpp. Build with -I include, then deliberately define a function body in the header and include it from two .cpp files to see the linker error.

Before you continue

The program builds with -std=c++17 and no warnings
You can explain the key rule without reading the example
The normal and edge cases both have recorded results

If something goes wrong

The compiler reports that a name or type is unknown.

Start at the first error. Check spelling, required #include lines, and whether the declaration appears before use.

The program runs but the value is wrong.

Print the inputs and intermediate values, then check conversions, units, and collection order.