Заголовки в C++: с чего начать без путаницы

За полчаса вы разложите одну функцию по паре файлов: объявление в .h, определение в .cpp, — соберёте проект и поймёте, почему компилятор ругается на «multiple definition», если сделать неправильно. Всё на C++17 и любом свежем компиляторе: g++ 11+, clang 14+ или MSVC из Visual Studio 2022. Ничего, кроме компилятора и текстового редактора, не нужно.

Что нужно иметь до начала

Проверьте, что у вас установлено, прежде чем копировать код ниже:

• компилятор с поддержкой C++17. Проверка в терминале: g++ --version или clang++ --version. Для MSVC откройте «Developer Command Prompt» и введите cl;
• любой редактор — VS Code, CLion, Notepad++, хоть блокнот;
• терминал в папке проекта, где будете запускать команду сборки.

Если g++ --version выдаёт версию 4 или 5 — компилятор старый, но для этого примера хватит. Всё, что здесь используется, работает и на C++11.

Зачем вообще делить код на два файла

Пока программа в одном файле — заголовки не нужны. Проблема появляется, когда файлов становится несколько. Функцию, написанную в math_utils.cpp, из main.cpp просто так не видно: компилятор обрабатывает каждый .cpp отдельно и о содержимом соседнего файла не знает.

Заголовок (.h) — это способ сказать другим файлам: «такая функция существует, вот её имя и типы аргументов». А сама реализация лежит в .cpp. Одно предложение о том, почему так: разделение на объявление и определение позволяет компилировать файлы независимо, а компоновщику — потом собрать их вместе.

Заголовок отвечает на вопрос «что есть», исходник — на вопрос «как это работает». Если вы кладёте тело функции в .h, вы стираете эту границу и обычно получаете ошибку компоновки.

Шаги

1. Создайте файл math_utils.h с объявлением функции. Точка с запятой в конце — вместо тела:

   // math_utils.h
   #ifndef MATH_UTILS_H
   #define MATH_UTILS_H
   
   // Складывает два целых числа и возвращает результат
   int add(int a, int b);
   
   #endif // MATH_UTILS_H
   

   Проверка: в файле нет фигурных скобок с телом функции, только объявление со ;.

2. Создайте файл math_utils.cpp с реализацией. В первой строке подключите свой же заголовок:

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

   Проверка: сигнатура int add(int a, int b) совпадает с той, что в заголовке, до последнего символа.

3. Создайте main.cpp, подключите заголовок и вызовите функцию:

   // main.cpp
   #include <iostream>
   #include "math_utils.h"
   
   int main() {
       int result = add(2, 3);
       std::cout << "2 + 3 = " << result << std::endl;
       return 0;
   }
   

   Проверка: вы подключаете math_utils.h, а не math_utils.cpp. Исходники в #include не подключают.

4. Соберите оба .cpp одной командой. Заголовок в команде не указывается — он подтягивается через #include:

   g++ -std=c++17 main.cpp math_utils.cpp -o app

   Для clang замените g++ на clang++. Для MSVC: cl /std:c++17 main.cpp math_utils.cpp.

   Проверка: в папке появился файл app (или app.exe на Windows), ошибок в терминале нет.

5. Запустите:

   ./app

   Проверка: в терминале выводится строка 2 + 3 = 5. Если да — заголовок и исходник связались правильно.

Что за строки с решёткой в начале заголовка

Три строки — #ifndef, #define, #endif — это include guard^*. Они защищают от того, что содержимое заголовка попадёт в один и тот же .cpp дважды. Такое случается, когда файл A.h подключает B.h, а ваш исходник подключает оба напрямую.

^* Include guard — защита от повторного включения. При первом подключении MATH_UTILS_H ещё не определён, поэтому код внутри попадает в компиляцию и макрос определяется. При втором подключении #ifndef уже ложен, и блок пропускается.

Имя макроса (MATH_UTILS_H) должно быть уникальным в пределах проекта — обычно его делают из имени файла заглавными буквами. Альтернатива, которую поддерживают все современные компиляторы, — одна строка #pragma once вместо трёх. Она короче, но формально нестандартна; классический include guard работает везде.

Главное правило: что можно в заголовке, а что нет

Заголовок подключается в несколько .cpp. Если в нём лежит определение обычной функции, оно попадёт в каждый из них — и компоновщик увидит несколько одинаковых функций. Это и есть ошибка «multiple definition».

Запомните на старте одно: в заголовок — объявления, в исходник — тела. Шаблоны и inline — исключения, к ним вернётесь позже, когда они понадобятся.

Если не получилось

• undefined reference to 'add(int, int)' (или unresolved external symbol в MSVC). Компилятор нашёл объявление, но не нашёл тело. Причина почти всегда одна: вы забыли добавить math_utils.cpp в команду сборки. Проверьте, что в g++ перечислены оба .cpp.
• multiple definition of 'add(int, int)'. Тело функции попало в заголовок и размножилось. Перенесите его в .cpp, в .h оставьте только объявление со ;. Либо, если это осознанно, пометьте функцию inline.
• fatal error: math_utils.h: No such file or directory. Компилятор не нашёл заголовок. Проверьте имя в кавычках #include "math_utils.h" и то, что файл лежит в той же папке, что и исходник.
• redefinition of 'add' при сборке одного файла. В один .cpp заголовок попал дважды, а include guard отсутствует или у двух заголовков совпало имя макроса. Добавьте #ifndef/#define/#endif с уникальным именем.
• Собирается, но при запуске выводит не то. Сигнатуры в .h и .cpp разошлись — например, в заголовке int add(int, int), а в исходнике long add(int, int). Компилятор считает их разными функциями. Сверьте типы посимвольно.

Что делать дальше

Когда пара файлов собирается — переходите к системе сборки, чтобы не перечислять исходники руками. Для старта хватит CMake: он сам найдёт все .cpp и пересоберёт только изменённое. Дальше по порядку стоит разобрать три темы, каждая из которых заслуживает отдельного чтения: почему шаблоны кладут целиком в заголовок; чем #include "..." в кавычках отличается от #include <...> в угловых скобках; и что такое forward declaration, которое ускоряет компиляцию и разрывает циклические зависимости между заголовками.