2.11 — Header files

In this lesson, you'll learn about header files, understand how they solve the problem of forward declarations in multi-file programs, and discover how to create and use your own header files effectively.

The forward declaration problem

In the previous lessons, we saw how to split programs across multiple files. But there's a significant problem: we need to forward declare functions in every file that uses them:

math_operations.cpp

double add(double a, double b)
{
    return a + b;
}

double subtract(double a, double b)
{
    return a - b;
}

double multiply(double a, double b)
{
    return a * b;
}

calculator.cpp

#include <iostream>

// We need these forward declarations to use the functions
double add(double a, double b);
double subtract(double a, double b);
double multiply(double a, double b);

int main()
{
    double result1 = add(5.0, 3.0);
    double result2 = subtract(10.0, 4.0);
    double result3 = multiply(2.0, 6.0);
    
    std::cout << "Results: " << result1 << ", " << result2 << ", " << result3 << std::endl;
    
    return 0;
}

statistics.cpp

#include <iostream>

// We need the same forward declarations again!
double add(double a, double b);
double subtract(double a, double b);
double multiply(double a, double b);

double calculateMean(double a, double b)
{
    return add(a, b) / 2.0;
}

double calculateRange(double a, double b)
{
    return subtract(a, b);  // Assumes a > b
}

int main()
{
    double mean = calculateMean(10.0, 20.0);
    std::cout << "Mean: " << mean << std::endl;
    
    return 0;
}

This approach has serious problems:

• Code duplication: Same forward declarations in multiple files
• Maintenance nightmare: If a function signature changes, update every file
• Error-prone: Easy to make mistakes when copying declarations
• Hard to manage: Difficult to keep track of all dependencies

What are header files?

Header files solve this problem. They are files (typically with .h or .hpp extension) that contain:

• Function declarations (forward declarations)
• Type definitions
• Constants
• Class declarations
• Other shared code that multiple source files need

Creating your first header file

Let's solve our math operations problem with a header file:

math_operations.h (header file)

// math_operations.h - Header file for mathematical operations
#ifndef MATH_OPERATIONS_H
#define MATH_OPERATIONS_H

// Function declarations
double add(double a, double b);
double subtract(double a, double b);
double multiply(double a, double b);
double divide(double a, double b);

// Constants
const double PI = 3.14159265359;
const double E = 2.71828182846;

#endif // MATH_OPERATIONS_H

math_operations.cpp (implementation file)

// math_operations.cpp - Implementation of mathematical operations
#include "math_operations.h"  // Include our own header

double add(double a, double b)
{
    return a + b;
}

double subtract(double a, double b)
{
    return a - b;
}

double multiply(double a, double b)
{
    return a * b;
}

double divide(double a, double b)
{
    return a / b;  // Caller should check for division by zero
}

main.cpp (using the header)

#include <iostream>
#include "math_operations.h"  // Include our header

int main()
{
    double x = 10.0, y = 3.0;
    
    std::cout << "x + y = " << add(x, y) << std::endl;
    std::cout << "x - y = " << subtract(x, y) << std::endl;
    std::cout << "x * y = " << multiply(x, y) << std::endl;
    std::cout << "x / y = " << divide(x, y) << std::endl;
    
    std::cout << "Pi = " << PI << std::endl;
    std::cout << "e = " << E << std::endl;
    
    return 0;
}

Compile with:

g++ main.cpp math_operations.cpp -o calculator

Output:

x + y = 13
x - y = 7
x * y = 30
x / y = 3.33333
Pi = 3.14159
e = 2.71828

Header guards (preview)

Notice the #ifndef, #define, and #endif in the header? These are header guards (covered in detail in lesson 2.12). They prevent the header from being included multiple times in the same file.

A more comprehensive example

Let's create a student management system with proper header files:

student.h

#ifndef STUDENT_H
#define STUDENT_H

#include <string>

// Function declarations
double calculateGPA(const double grades[], int count);
char getLetterGrade(double percentage);
void displayStudentReport(const std::string& name, const double grades[], int count);
bool isPassingGrade(double grade);
double findHighestGrade(const double grades[], int count);
double findLowestGrade(const double grades[], int count);

// Constants
const double PASSING_GRADE = 60.0;
const int MAX_GRADES = 10;

#endif // STUDENT_H

student.cpp

#include "student.h"
#include <iostream>

double calculateGPA(const double grades[], int count)
{
    if (count <= 0) return 0.0;
    
    double total = 0.0;
    for (int i = 0; i < count; ++i)
    {
        total += grades[i];
    }
    
    return total / count;
}

char getLetterGrade(double percentage)
{
    if (percentage >= 90.0) return 'A';
    else if (percentage >= 80.0) return 'B';
    else if (percentage >= 70.0) return 'C';
    else if (percentage >= 60.0) return 'D';
    else return 'F';
}

void displayStudentReport(const std::string& name, const double grades[], int count)
{
    std::cout << "\n=== Student Report ===" << std::endl;
    std::cout << "Student: " << name << std::endl;
    std::cout << "Grades: ";
    
    for (int i = 0; i < count; ++i)
    {
        std::cout << grades[i];
        if (i < count - 1) std::cout << ", ";
    }
    std::cout << std::endl;
    
    double gpa = calculateGPA(grades, count);
    char letter = getLetterGrade(gpa);
    
    std::cout << "Average: " << gpa << std::endl;
    std::cout << "Letter Grade: " << letter << std::endl;
    std::cout << "Status: " << (isPassingGrade(gpa) ? "PASSING" : "FAILING") << std::endl;
    std::cout << "Highest Grade: " << findHighestGrade(grades, count) << std::endl;
    std::cout << "Lowest Grade: " << findLowestGrade(grades, count) << std::endl;
}

bool isPassingGrade(double grade)
{
    return grade >= PASSING_GRADE;
}

double findHighestGrade(const double grades[], int count)
{
    if (count <= 0) return 0.0;
    
    double highest = grades[0];
    for (int i = 1; i < count; ++i)
    {
        if (grades[i] > highest)
            highest = grades[i];
    }
    
    return highest;
}

double findLowestGrade(const double grades[], int count)
{
    if (count <= 0) return 0.0;
    
    double lowest = grades[0];
    for (int i = 1; i < count; ++i)
    {
        if (grades[i] < lowest)
            lowest = grades[i];
    }
    
    return lowest;
}

input.h

#ifndef INPUT_H
#define INPUT_H

#include <string>

// Function declarations for input operations
std::string getStudentName();
double getGrade(int gradeNumber);
int getNumberOfGrades();
bool getUserConfirmation(const std::string& message);

#endif // INPUT_H

input.cpp

#include "input.h"
#include "student.h"  // For MAX_GRADES constant
#include <iostream>

std::string getStudentName()
{
    std::cout << "Enter student name: ";
    std::string name;
    std::getline(std::cin, name);
    return name;
}

double getGrade(int gradeNumber)
{
    double grade;
    do
    {
        std::cout << "Enter grade " << gradeNumber << " (0-100): ";
        std::cin >> grade;
        
        if (grade < 0 || grade > 100)
        {
            std::cout << "Invalid grade. Please enter a value between 0 and 100." << std::endl;
        }
    } while (grade < 0 || grade > 100);
    
    return grade;
}

int getNumberOfGrades()
{
    int count;
    do
    {
        std::cout << "How many grades will you enter (1-" << MAX_GRADES << ")? ";
        std::cin >> count;
        
        if (count <= 0 || count > MAX_GRADES)
        {
            std::cout << "Please enter a number between 1 and " << MAX_GRADES << "." << std::endl;
        }
    } while (count <= 0 || count > MAX_GRADES);
    
    std::cin.ignore();  // Clear newline from input buffer
    return count;
}

bool getUserConfirmation(const std::string& message)
{
    char response;
    std::cout << message << " (y/n): ";
    std::cin >> response;
    return (response == 'y' || response == 'Y');
}

main.cpp

#include <iostream>
#include "student.h"    // For student operations
#include "input.h"      // For input operations

int main()
{
    std::cout << "=== Student Grade Management System ===" << std::endl;
    
    std::string studentName = getStudentName();
    int numGrades = getNumberOfGrades();
    
    // Get grades from user
    double grades[MAX_GRADES];  // Using constant from student.h
    for (int i = 0; i < numGrades; ++i)
    {
        grades[i] = getGrade(i + 1);
    }
    
    // Display the report
    displayStudentReport(studentName, grades, numGrades);
    
    // Ask if user wants to see additional analysis
    if (getUserConfirmation("Show additional analysis?"))
    {
        double gpa = calculateGPA(grades, numGrades);
        std::cout << "\nAdditional Analysis:" << std::endl;
        std::cout << "Grade distribution: ";
        
        if (gpa >= 90) std::cout << "Excellent performance!" << std::endl;
        else if (gpa >= 80) std::cout << "Good performance!" << std::endl;
        else if (gpa >= 70) std::cout << "Satisfactory performance." << std::endl;
        else if (gpa >= 60) std::cout << "Needs improvement." << std::endl;
        else std::cout << "Poor performance - consider tutoring." << std::endl;
    }
    
    return 0;
}

Compile with:

g++ main.cpp student.cpp input.cpp -o student_system

Header file best practices

✅ Good header file practices:

// geometry.h - Good header file example
#ifndef GEOMETRY_H
#define GEOMETRY_H

// 1. Include only what you need
#include <string>

// 2. Use const for constants instead of #define
const double PI = 3.14159265359;

// 3. Organize declarations logically
// Circle functions
double calculateCircleArea(double radius);
double calculateCircleCircumference(double radius);

// Rectangle functions
double calculateRectangleArea(double width, double height);
double calculateRectanglePerimeter(double width, double height);

// Utility functions
std::string formatMeasurement(double value, const std::string& unit);

#endif // GEOMETRY_H

// geometry.cpp - Implementation file
#include "geometry.h"
#include <iostream>
#include <iomanip>
#include <sstream>

double calculateCircleArea(double radius)
{
    return PI * radius * radius;
}

double calculateCircleCircumference(double radius)
{
    return 2 * PI * radius;
}

double calculateRectangleArea(double width, double height)
{
    return width * height;
}

double calculateRectanglePerimeter(double width, double height)
{
    return 2 * (width + height);
}

std::string formatMeasurement(double value, const std::string& unit)
{
    std::ostringstream oss;
    oss << std::fixed << std::setprecision(2) << value << " " << unit;
    return oss.str();
}

❌ Avoid these patterns:

// bad_header.h - What NOT to do

// Don't forget header guards
// #ifndef BAD_HEADER_H  <-- Missing!
// #define BAD_HEADER_H

// Don't include unnecessary headers
#include <iostream>     // Only needed if header uses cout/cin
#include <vector>       // Only needed if header uses vector
#include <algorithm>    // Only needed if header uses algorithms
#include <fstream>      // Only needed if header uses file streams

// Don't use 'using namespace' in headers
using namespace std;    // BAD! Pollutes global namespace for all users

// Don't define functions in headers (unless inline)
void badFunction()      // BAD! Should be in .cpp file
{
    cout << "This doesn't belong here!" << endl;
}

// Don't use global variables in headers
int globalCounter = 0;  // BAD! Creates definition in every file that includes this

// #endif  <-- Also missing!

System headers vs user headers

System headers (angle brackets)

#include <iostream>     // Standard library header
#include <string>       // Standard library header
#include <vector>       // Standard library header

User headers (quotes)

#include "myheader.h"      // User-defined header in same directory
#include "utils/math.h"    // User-defined header in subdirectory
#include "../common.h"     // User-defined header in parent directory

Real-world header organization

In larger projects, headers are often organized like this:

project/
├── src/
│   ├── main.cpp
│   ├── math/
│   │   ├── arithmetic.h
│   │   ├── arithmetic.cpp
│   │   ├── geometry.h
│   │   └── geometry.cpp
│   ├── ui/
│   │   ├── interface.h
│   │   ├── interface.cpp
│   │   ├── display.h
│   │   └── display.cpp
│   └── utils/
│       ├── string_utils.h
│       ├── string_utils.cpp
│       ├── file_utils.h
│       └── file_utils.cpp

Each directory contains related headers and implementation files.

Benefits of header files

Organization:

• Group related declarations together
• Clear separation of interface (header) and implementation (source)

Maintainability:

• Change function signature in one place (the header)
• All files using the function get updated automatically

Reusability:

• Headers can be included in multiple projects
• Standard interface for accessing functionality

Collaboration:

• Team members can work with headers before implementations are complete
• Clear contracts between different parts of the code

Documentation:

• Headers serve as documentation of available functionality
• Easy to see what functions/constants are available

Common header file mistakes

Mistake 1: Forgetting to include the header in its own implementation

// math_operations.cpp - BAD!
// #include "math_operations.h"  <-- Forgot this!

double add(double a, double b)  // Compiler might not catch signature mismatches
{
    return a + b;
}

Mistake 2: Circular includes

// a.h
#include "b.h"
// ... rest of a.h

// b.h
#include "a.h"  // Creates circular dependency!
// ... rest of b.h

Mistake 3: Including source files

#include "math_operations.cpp"  // WRONG! Include the .h file, not .cpp

Summary

Header files are essential for organizing larger C++ programs:

Key concepts:

• Header files: Contain declarations, constants, and shared code
• Implementation files: Contain function definitions
• Include directive: #include brings header contents into source files
• Header guards: Prevent multiple inclusion problems

Benefits:

• Eliminate code duplication: Declare functions once, use everywhere
• Improve maintainability: Change signatures in one place
• Better organization: Clear separation of interface and implementation
• Enable reusability: Headers can be shared between projects

Best practices:

• Always use header guards
• Include only what you need
• Never use using namespace in headers
• Keep implementations in .cpp files
• Use meaningful file names and organization

File extensions:

• .h or .hpp for headers
• .cpp for implementation files

Header files are the foundation of modular C++ programming and essential for any project beyond simple single-file programs.

Quiz

1. What problems do header files solve?
2. What should go in a header file vs. an implementation file?
3. What's the difference between #include <file> and #include "file"?
4. Why shouldn't you use using namespace in header files?
5. What's the purpose of header guards?

Practice exercises

Try these exercises to master header files:

1. Math library: Create a comprehensive math library with separate headers for basic operations, geometry, and statistics
2. Text processor: Build a text processing system with headers for input, analysis, and output functions
3. Game engine: Design headers for a simple game engine (graphics, input, physics, audio)
4. Refactor existing code: Take a large single-file program and split it into logical headers and implementation files