Include guards і директива #pragma once

1. Проблема повторного включення заголовків

Коли ви лише починаєте працювати над проєктом, може здаватися, що #include — це «підʼєднати файл», майже як «додати бібліотеку». Але логіка препроцесора значно простіша: #include — це саме препроцесорна директива, і вона не «підʼєднує» файл, а буквально вставляє текст одного файла всередину іншого.

Тобто #include "task.hpp" за змістом близький до фрази «візьми вміст task.hpp і встав сюди, ніби я вручну його скопіював». І саме тут починається найцікавіше: той самий заголовок може опинитися в одному .cpp не лише тому, що ви явно написали #include двічі, а й тому, що підʼєднали інший заголовок, який усередині теж підʼєднує перший. Це називається транзитивним включенням, і працює воно як доміно.

Уявімо такий ланцюжок підключень:

flowchart TD
    Main[main.cpp] --> IO[task_io.hpp]
    Main --> Task[task.hpp]
    IO --> Task

У main.cpp ви написали два #include, а один із них — task_io.hpp — усередині теж підʼєднує task.hpp. Підсумок: task.hpp опинився тут двічі. І якщо ви не вжили запобіжних заходів, компілятор побачить повторні оголошення й влаштує вам «redefinition party» — вечірку, на яку навряд чи хтось хотів би потрапити.

Типовий симптом: повторне оголошення

Думка «ну й що, нехай підʼєднається двічі» — цілком людська. Але компілятор — істота суворих правил: якщо він бачить визначення структури або функції двічі в одному й тому самому місці, то після «текстової вставки» все саме так і виглядає, він вважає, що ви намагаєтеся оголосити одне й те саме повторно.

Найчастіший сценарій — повторне визначення struct.

Наприклад, уявімо наївний заголовок:

// task.hpp (наївна версія — так робити не варто)
struct Task {
    int id{};
};

І файл:

// main.cpp
#include "task.hpp"
#include "task.hpp"  // повторно, випадково або навмисно

int main() {
    Task t{1};
}

Без захисту заголовка компілятор «побачить» два однакових struct Task { ... }; підряд і скаже щось на кшталт: «Task уже визначено».

Важливо зрозуміти: це не «примха», а захист цілісності програми. Якби мова дозволяла дві різні версії Task з однаковим імʼям в одному місці, ви не змогли б передбачити, який саме Task насправді опиниться в памʼяті. У світі C++ така непередбачувана поведінка зазвичай закінчується дуже творчими багами.

Препроцесор: де виникає проблема

Перш ніж розвʼязувати проблему, важливо побачити, на якому рівні вона виникає. До того як компілятор почне розбирати C++-синтаксис, код проходить стадію препроцесінгу — обробки рядків, що починаються з #.

Для нас сьогодні важливі лише кілька директив:

• #include — вставка тексту з іншого файла;
• #ifndef / #define / #endif — умовна вставка тексту залежно від того, чи визначено макрос;
• #pragma once — «обіцянка» обробити цей файл не більш ніж один раз.

Процес можна уявити так:

flowchart LR
    A[Вихідні файли .cpp/.hpp] --> B[Препроцесор: #include, #define...]
    B --> C[Компілятор: синтаксис C++]
    C --> D[Компонувальник: збирання програми]

Наша проблема повторного включення зʼявляється саме на етапі B. Отже, і розвʼязання буде на цьому самому рівні: ми маємо пояснити препроцесору, що один і той самий заголовок не можна вставляти двічі.

2. Include guard

Include guard як «перемикач»

Include guard — це простий і дуже надійний підхід: ми вводимо макрос, який означає «цей заголовок уже було включено». Під час першого включення такого макроса ще немає — ми його визначаємо, і далі проходить увесь інтерфейс. Під час повторного включення макрос уже існує, тож увесь заголовок пропускається.

Шаблон має такий вигляд:

#ifndef SOME_UNIQUE_NAME_HPP
#define SOME_UNIQUE_NAME_HPP

// ... вміст заголовка ...

#endif

Застосуймо це до нашого навчального проєкту. Нехай у нас є модель Task — задача в консольному застосунку. Назвемо його умовно TaskBook, щоб було відчутно, що ми збираємо щось цілісне, а не просто пишемо окремі фрагменти.

// task.hpp
#ifndef TASKBOOK_TASK_HPP
#define TASKBOOK_TASK_HPP

struct Task {
    int id{};
};

#endif // TASKBOOK_TASK_HPP

Тепер, навіть якщо task.hpp буде включено хоч десять разів через ланцюжок підключень, у підсумковий «склеєний» текст він потрапить лише один раз.

Як guard працює крок за кроком

На словах «макрос визначено/не визначено» це звучить дещо абстрактно, тож розберімо механіку. Уявіть, що препроцесор веде таблицю визначених макросів — умовний «словничок».

Події відбуваються так:

Тобто include guard — це буквально механізм «включити лише один раз».

Щоб переконатися в цьому на практиці, можна навіть навмисно включити заголовок двічі й подивитися, що компілятор не скаржиться:

// main.cpp
#include "task.hpp"
#include "task.hpp" // повторно — тепер безпечно

int main() {
    Task t{42};
    (void)t;
}

Так, це виглядає дивно — зазвичай так не роблять. Але як демонстрація це працює ідеально: захист має витримувати навіть неакуратне підключення через #include.

Як називати макрос-сторож

Здається логічним назвати guard якось коротко: TASK_HPP. І часто це навіть «працює»… доки проєкт не виросте, доки ви не підʼєднаєте сторонні бібліотеки, доки не почнете збирати кілька модулів разом.

Проблема в тому, що макроси живуть у доволі «глобальному» світі препроцесора. Якщо десь у проєкті або в чужій бібліотеці вже є TASK_HPP, ваш guard перестає коректно захищати саме ваш файл: препроцесор скаже «а, макрос уже визначено» і пропустить заголовок, навіть якщо його ще жодного разу фактично не вставляли. Це дуже неприємний різновид бага, бо назовні він виглядає як «чому компілятор раптом не бачить мій тип?».

Тому практичне правило може звучати трохи нудно, але воно добре береже нерви: імʼя має бути достатньо унікальним, зазвичай із префіксом проєкту або модуля.

Варіанти, які зазвичай живуть довго й щасливо:

task.hpp

TASK_HPP

TASKBOOK_TASK_HPP

task_io.hpp

IO_HPP

TASKBOOK_TASK_IO_HPP

config.hpp

CONFIG_HPP

TASKBOOK_CONFIG_HPP

Так, виглядає довго. Але це саме той випадок, коли довге імʼя — не «зайва писанина», а страховка від випадкових збігів.

Guard має охоплювати весь інтерфейс

Коли студенти вперше пишуть include guard, типова помилка — обгорнути не весь файл, наприклад лише struct, а частину коду залишити зовні. Це призводить до дивних ефектів: частина заголовка захищена, частина — ні, і ви знову отримуєте повторні оголошення.

Найкраще дотримуватися простого правила: майже весь файл заголовка має лежати всередині guard. Зазвичай зовні залишають лише коментар-шапку, і то не завжди, а далі одразу ставлять guard або #pragma once.

Ось охайний шаблон із guard:

// task_io.hpp
#ifndef TASKBOOK_TASK_IO_HPP
#define TASKBOOK_TASK_IO_HPP

#include <string>

struct TaskLine {
    std::string text;
};

#endif // TASKBOOK_TASK_IO_HPP

Якщо ви випадково винесете щось за межі guard, воно може повторитися. А в заголовках найчастіше повторюються саме визначення типів, constexpr-змінних, inline-функцій та інші речі, до яких компілятор ставиться дуже ревниво. Про те, які визначення можна тримати в заголовках і чому, ми поговоримо пізніше; сьогодні нам важлива саме механіка «не включати повторно».

3. #pragma once

Короткий сучасний варіант

Після include guards #pragma once сприймається як «а що, так можна було?». Так, можна: це директива препроцесора, яка каже компілятору: «цей файл обробляй не більш ніж один раз».

Приклад:

// config.hpp
#pragma once

struct Config {
    int autosave_seconds{};
};

Переваги очевидні: менше шаблонного коду, неможливо забути #endif, неможливо помилитися в імені макроса.

Але є нюанс, через який у навчальних курсах зазвичай спершу показують guards. #pragma once історично не був частиною стандарту C++ — це саме #pragma, тобто «підказка» компілятору. На практиці його підтримують майже всі сучасні компілятори, і в реальних проєктах він трапляється постійно.

Найпрактичніший підхід для нас зараз такий: обидва способи розвʼязують ту саму задачу, а в проєкті важливо просто вибрати один стиль і послідовно його дотримуватися, щоб код виглядав однаково й не перетворювався на «клаптикову ковдру».

4. Практичний мініприклад

Як повторне включення зʼявляється саме собою

Щоб відчути проблему на практиці, зберімо невеликий фрагмент нашого TaskBook. Нехай у нас є task.hpp і task_print.hpp. Нам потрібне виведення задачі в консоль, але поки не хочеться ускладнювати проєкт, тож обмежимося однією функцією друку.

Спочатку task.hpp:

// task.hpp
#ifndef TASKBOOK_TASK_HPP
#define TASKBOOK_TASK_HPP

struct Task {
    int id{};
};

#endif // TASKBOOK_TASK_HPP

Тепер task_print.hpp, який використовує Task. Він цілком логічно включає task.hpp:

// task_print.hpp
#ifndef TASKBOOK_TASK_PRINT_HPP
#define TASKBOOK_TASK_PRINT_HPP

#include "task.hpp"
#include <iostream>

inline void print_task(const Task& t) {
    std::cout << "Task id = " << t.id << '\n'; // Task id = 7
}

#endif // TASKBOOK_TASK_PRINT_HPP

А тепер main.cpp. Уявімо, що програміст, тобто ви після важкого тижня, вирішив для підстраховки підʼєднати і task.hpp, і task_print.hpp:

// main.cpp
#include "task.hpp"
#include "task_print.hpp" // усередині вже є #include "task.hpp"

int main() {
    Task t{7};
    print_task(t);
}

Без include guards у task.hpp цей код легко призвів би до повторного визначення Task. Із guards — ні: вдруге task.hpp просто «мовчки» пропускається.

І це ключова думка: ми не можемо вручну контролювати всі ланцюжки #include, особливо коли проєкт зростає. Тому захист заголовків — не просто «гарний стиль», а частина інженерної гігієни.

Навіть у матеріалах стандарту C++ трапляються правки, повʼязані з тим, що приклад має явно підʼєднувати потрібний заголовок. Інакше він стає надто крихким і залежить від випадкових підключень.

5. Типові помилки під час використання include guards і #pragma once

Помилка № 1: забули #endif, і заголовок перетворюється на «чорну діру».
Найприкріший сценарій: ви написали #ifndef, #define, потім багато коду, а #endif забули. У результаті препроцесор вважає, що умовний блок тягнеться далі, і починає дивно обробляти все, що йде після. Такий баг може «вистрілити» помилкою взагалі в іншому файлі, і це виглядає майже як містика. Розвʼязання просте: дотримуйтеся одного й того самого шаблону й завжди закривайте guard коментарем // SOME_NAME.

Помилка № 2: guard охоплює не весь заголовок.
Іноді частина оголошень або #include лишається зовні. Потім заголовок підʼєднується вдруге, і «незахищена» частина повторюється. Підсумок — знову redefinition або інші сюрпризи. Тут добре допомагає проста звичка: guard або #pragma once пишемо на самому початку файла й виходимо з того, що майже весь .hpp має бути «всередині».

Помилка № 3: надто загальне імʼя макроса (TASK_HPP), яке конфліктує з чужим кодом.
Поки проєкт маленький, цю небезпеку легко недооцінити. Але щойно зʼявляться сторонні бібліотеки або просто інший модуль зі схожими назвами, збіг макросів може призвести до того, що потрібний заголовок почне «раптово пропускатися». Це виглядає як «компілятор не бачить мій тип», хоча файл начебто підключено. Допомагає довгий, унікальний префікс: TASKBOOK_TASK_HPP.

Помилка № 4: змішування підходів в одному проєкті без причини.
Технічно можна частину заголовків захищати guards, а частину — #pragma once, і все працюватиме. Але код стає менш однорідним, а новачкам складніше читати й підтримувати проєкт. Зазвичай обирають один стиль для всього репозиторію й дотримуються його, щоб не виникало відчуття, ніби проєкт писали пʼятеро людей у пʼяти різних всесвітах.

Помилка № 5: віра в те, що «якщо я акуратно розставляю #include, повторного включення не буде».
Це майже завжди ілюзія контролю. Сьогодні у вас main.cpp включає A.hpp, завтра ви підʼєднали B.hpp, а всередині нього виявився A.hpp, післязавтра переставили рядки місцями — і раптом усе зламалося. Include guard потрібен саме тому, що людина не повинна вручну стежити за графом підключень: нехай цим займається проста, але надійна механіка препроцесора.