Циклічні залежності: як із ними впоратися

1. Що таке циклічна залежність

Зазвичай циклічні залежності зʼявляються не в перший день, коли у вас є лише один main.cpp і три cout, а тоді, коли ви вже «по-дорослому» розкладаєте код по файлах і починаєте моделювати дані кількома типами.

Цикл — це ситуація, коли заголовок A.hpp включає B.hpp, а B.hpp — A.hpp безпосередньо або через ланцюжок інших включень. Формально це орієнтований граф залежностей, у якому є цикл. На практиці ж компіляція раптом починає засипати вас дивними повідомленнями про incomplete type, unknown type name або field has incomplete type.

Як це виглядає на схемі

flowchart TD
    A[A.hpp] --> B[B.hpp]
    B --> A

Чому include guards не рятують

Дуже поширена помилка новачків звучить так: «Але ж у мене в обох файлах стоїть #pragma once, отже цикл має зникнути». Ні. #pragma once і include guards розвʼязують іншу проблему: повторне включення одного й того самого файла в одну одиницю трансляції. Тобто вони запобігають нескінченному «вкладанню» файла у файл.

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

Типовий результат — помилка на кшталт «поле має неповний тип», тому що компілятор дійшов до рядка Project project;, а Project ще не визначено.

Як розпізнати цикл за помилками компілятора

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

Нижче — невелика таблиця-підказка: що шукати в повідомленні компілятора і де зазвичай ховається причина.

unknown type name 'X'
X does not name a type

field has incomplete type 'X'

invalid use of incomplete type 'X'

помилка «зникає», якщо змінити порядок #include у .cpp

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

2. Приклад: Task і Project легко утворюють цикл

Щоб не говорити про цикли абстрактно, продовжимо наш навчальний CLI-проєкт. Нехай це буде мініпланувальник задач: у нас є Task (задача) і Project (проєкт).

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

Почнімо з версії, яка виглядає природно, але призводить до проблеми.

task.hpp (наївно)

// task.hpp
#pragma once
#include "project.hpp"

struct Task {
    int id{};
    Project project; // хочемо зберігати проєкт «за значенням»
};

project.hpp (наївно)

// project.hpp
#pragma once
#include <vector>
#include "task.hpp"

struct Project {
    int id{};
    std::vector<Task> tasks; // хочемо зберігати задачі «за значенням»
};

За змістом усе виглядає логічно: проєкт зберігає задачі, а задача — проєкт. Але з погляду механіки C++ ми влаштували «замкнений ланцюг вимог»: щоб визначити Task, потрібен повний Project; щоб визначити Project, потрібен повний Task. І тут компілятор уже не може «вгадати», що саме має бути визначене раніше.

3. Як розірвати цикл

Розірвати цикл — означає перестати вимагати «повний тип» там, де він насправді не потрібен, і тримати заголовки максимально легкими. Нижче — три найуживаніші стратегії.

Спосіб 1: forward declaration + вказівник або посилання

Найпростіший спосіб — перестати вимагати повний тип у заголовку. Повний тип потрібен тоді, коли ви зберігаєте обʼєкт за значенням (Project project;). Якщо ж зберігати вказівник (Project* project;) або посилання (Project& project;), то в заголовку достатньо знати, що тип існує, — тобто вистачає forward declaration.

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

task.hpp (розриваємо цикл)

// task.hpp
#pragma once

struct Project; // попереднє оголошення

struct Task {
    int id{};
    Project* project{}; // OK: вказівник на неповний тип
};

Тепер task.hpp більше не включає project.hpp. Отже, цикл уже розірвано.

project.hpp (може включати task.hpp)

// project.hpp
#pragma once
#include <vector>
#include "task.hpp"

struct Project {
    int id{};
    std::vector<Task> tasks; // OK: Task тут повний, бо підключили task.hpp
};

А де тепер звертатися до project->... усередині функцій? Там, де ми маємо повне визначення Project, тобто у .cpp.

task.cpp (там, де потрібен доступ до полів Project)

// task.cpp
#include "task.hpp"
#include "project.hpp"

int get_project_id(const Task& t) {
    return t.project ? t.project->id : -1;
}

Зверніть увагу: у .cpp можна дозволити собі більше #include, тому що це не роздуває публічний інтерфейс заголовка. У заголовку ми мінімізуємо залежності, а у .cpp забезпечуємо компіляцію реалізації.

Спосіб 2: переносимо #include із .hpp у .cpp

Цикл часто виникає не тому, що типи справді «взаємно володіють» одне одним, а тому, що ми за звичкою підключили щось «на всяк випадок». Наприклад, ви оголосили в заголовку функцію, яка приймає const Project&, і вирішили включити project.hpp, хоча вам достатньо forward declaration.

Ідея проста: заголовок має містити лише мінімально потрібне для оголошень, а все, що необхідне для реалізації, переїжджає у .cpp.

Припустімо, у нас є функція друку задачі, і ми помилково вирішили підтягнути project.hpp у task.hpp.

Погана версія (зайва залежність у .hpp)

// task.hpp
#pragma once
#include "project.hpp"

struct Task {
    int id{};
    Project* project{};
};

void print_task(const Task& t);

Поліпшена версія (оголошення легке, реалізація — важча)

// task.hpp
#pragma once

struct Project; // достатньо, бо тут лише вказівник

struct Task {
    int id{};
    Project* project{};
};

void print_task(const Task& t);

// task.cpp
#include "task.hpp"
#include "project.hpp"
#include <iostream>

void print_task(const Task& t) {
    std::cout << "Задача #" << t.id << "\n";
}

Логіка така: заголовок не зобовʼязаний знати Project повністю, якщо він не розкриває деталей. А от .cpp має підключити все, що потрібно тілу функції.

Спосіб 3: змінюємо модель — зберігаємо ідентифікатор замість обʼєкта

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

Є простий і практичний варіант: замість самого обʼєкта зберігати ідентифікатор.

У невеликих CLI-проєктах це часто виявляється найстабільнішим розвʼязанням: менше звʼязності, менше includeʼів, менше проблем під час збирання.

task.hpp (посилаємося на проєкт через id)

// task.hpp
#pragma once

struct Task {
    int id{};
    int project_id{}; // звʼязок через число, а не через include
};

project.hpp

// project.hpp
#pragma once

struct Project {
    int id{};
};

Тепер у нас узагалі немає причин включати ці заголовки один в одного. А звʼязування відбувається на рівні логіки: наприклад, у «сховищі» (умовному storage.cpp) ви знаходите проєкт за project_id. Так, це додає ще один крок пошуку, зате різко зменшує звʼязність модулів і майже повністю прибирає цей клас проблем із циклічними include.

4. Міні-рефакторинг: робимо структуру, де цикл складніше «випадково» створити

Корисна звичка під час рефакторингу заголовків — прагнути до структури, де залежності йдуть в один бік: моделі → логіка → UI/друк. Навіть якщо ви поки не будуєте велику архітектуру, це дисциплінує проєкт.

Уявімо, що ми хочемо тримати моделі окремо, а друк — окремо. Тоді структура може виглядати так:

flowchart TD
    TaskH[task.hpp] --> TaskCpp[task.cpp]
    ProjectH[project.hpp] --> ProjectCpp[project.cpp]
    TaskCpp --> ProjectH
    PrintCpp[print.cpp] --> TaskH
    PrintCpp --> ProjectH

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

Ще одна практична перевірка: у кожному .cpp корисно першим підключати власний заголовок.

// task.cpp
#include "task.hpp"
#include "project.hpp"

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

5. Типові помилки під час розвʼязання циклічних залежностей

Помилка № 1: думати, що include guards «лікують» цикл повністю.
Include guards і #pragma once справді запобігають нескінченному включенню, але вони не роблять тип «раптом повним». Тому ситуація, коли «цикл зник, але тип неповний», — не рідкість, а майже стандартний сценарій. Розвʼязання тут не в тому, щоб «посилювати» guards, а в тому, щоб розривати залежність: forward declaration, перенесення include у .cpp або зміна моделі зберігання.

Помилка № 2: зробити forward declaration, а потім зберігати тип за значенням.
Дуже типовий крок новачка: написати struct Project;, відчути себе переможцем, а потім залишити Project project; у структурі. На жаль, компілятору потрібен розмір Project, щоб розкласти поля в памʼяті, а forward declaration цього розміру не повідомляє. Якщо вам потрібна композиція за значенням, підключайте заголовок із повним визначенням. Якщо ж хочеться зменшити залежності — переходьте на Project*, Project& або project_id.

Помилка № 3: використовувати неповний тип там, де потрібен доступ до полів, просто в заголовку.
Навіть якщо ви зберігаєте Project*, не можна в заголовку писати inline-реалізацію, яка робить project->id, якщо Project там ще неповний. Компілятор скаже invalid use of incomplete type. Правильне місце для такої логіки — .cpp, де ви підключили project.hpp.

Помилка № 4: «лагодити» цикл, додаючи ще більше #include.
Іноді, побачивши помилку, хочеться просто підключити все підряд: #include <iostream>, #include <vector>, #include "project.hpp", #include "task.hpp" у всіх місцях. На короткій дистанції це іноді «лікує» симптоми, але на довгій робить проєкт крихким і повільним: залежностей стає більше, цикли — складнішими, а збирання — важчим. Зазвичай правильніше спершу запитати себе: «Цей include потрібен для оголошення чи лише для реалізації?»

Помилка № 5: розірвати цикл вказівниками, але не продумати стан «вказівник порожній».
Щойно ви робите Project* project{}, ви допускаєте ситуацію, коли «проєкту немає». І навіть якщо у вашому сценарії проєкт буде завжди, код усе одно стане безпечнішим і зрозумілішим, якщо в місцях використання ви перевірятимете nullptr. Інакше ви виграли у компілятора, але програли рантайму — а рантайм, як правило, жартує гірше.