Попереднє оголошення

1. Що компілятор знає після попереднього оголошення

Якщо ви зараз думаєте: «Ну, підключу ще один заголовок — то й що?», то мислите як людина, яка одного дня напише #include <bits/stdc++.h>… а потім дивуватиметься, чому проєкт збирається довше, ніж готується кава. Проблема не в тому, що #include — зло. Проблема в тому, що #include — дорогий інструмент: він «вставляє» текст іншого файла, і компілятор змушений знову перетравлювати купу коду.

Ще одна проблема — крихкість. Заголовок може «випадково» компілюватися, бо потрібний тип підтягнувся транзитивно, через чийсь #include. Сьогодні ви переставили два рядки #include місцями — і раптом «std::string не знайдено» або «TaskStore не оголошено». Це не магія й не містика, а просто неконтрольовані залежності.

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

Як виглядає forward declaration

Зараз буде приємний момент: синтаксис forward declaration максимально нудний. А нудний синтаксис у C++ — це майже розкіш.

Попереднє оголошення типу виглядає так:

// десь у .hpp
struct User;

Цей рядок означає: тип User існує, але його будова (поля, розмір, нутрощі) поки що невідома.

Можливі такі варіанти:

struct User;   // для struct
class Engine;  // для class

З погляду компілятора в межах цієї теми struct і class тут відрізняються лише словом. Важливе інше: після такого оголошення тип стає неповним (incomplete type). Тобто компілятор знає імʼя типу, але не знає, скільки памʼяті він займає і які має поля.

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

Приклад:

// cli.hpp
#pragma once

namespace app {
    struct TaskStore; // попереднє оголошення в правильному просторі імен
}

Неповний тип: що можна, а що — ні

Щоб forward declaration не здавався «магічною мантрою», важливо чітко зрозуміти, що відбувається в голові компілятора. Після struct X; компілятор знає рівно одну річ: «є тип на імʼя X». Він не знає, скільки в нього полів, якого вони типу, який розмір у X, як його друкувати і з чого він складається. Це буквально «контакт у телефоні без номера й без фото».

І звідси випливає головне запитання: де можна використовувати неповний тип, а де не можна.

Зручно тримати в голові таку таблицю. Вона не замінює розуміння, зате економить час і нерви:

X* ptr;

X& ref; / const X& ref;

X

X value;

std::vector<X> items;

Сенс простий: якщо компілятору потрібно знати розмір або внутрішню будову типу, forward declaration не врятує. Якщо ж компілятору достатньо знати, що тип існує, а з його внутрішньою будовою ми працюватимемо пізніше (у .cpp), тоді forward declaration підходить.

2. Підхід: forward declaration у .hpp, #include — у .cpp

Forward declaration найчастіше використовують не «заради краси», а для цілком практичного розмежування відповідальності. Заголовок описує інтерфейс: які функції є, які типи беруть участь, які поля зберігає структура. Реалізація — у .cpp. Саме там ми можемо підключити все важке, що потрібно для внутрішньої логіки.

Уявімо: у нас є тип TaskStore і модуль cli, який взаємодіє з користувачем і викликає методи сховища. У заголовку CLI нам не потрібно знати, як влаштований TaskStore. Достатньо лише того, що він існує, бо ми зберігаємо на нього посилання або вказівник і оголошуємо функції.

Приклад: заголовок CLI з forward declaration

// cli.hpp
#pragma once

#include <string>

namespace app {
    struct TaskStore; // попереднє оголошення

    void run_cli(TaskStore& store, const std::string& username);
}

Тут заголовок cli.hpp залежить від <string>, оскільки використовує std::string у сигнатурі. А от TaskStore ми не підключаємо через "task_store.hpp", бо для оголошення функції достатньо forward declaration.

Приклад: реалізація CLI, де вже потрібен повний тип

// cli.cpp
#include "cli.hpp"
#include "task_store.hpp"   // тепер потрібен повний тип
#include <iostream>

namespace app {
    void run_cli(TaskStore& store, const std::string& username) {
        std::cout << "Привіт, " << username << "!\n"; // Привіт, Alice!
        store.add_task("Вивчити попередні оголошення"); // працюємо з TaskStore
    }
}

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

3. Практичний приклад: TaskStore + CLI з меншою звʼязністю

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

Зробимо три файли:

• task_store.hpp — структура-сховище задач.
• task_store.cpp — реалізація методів.
• cli.hpp/cli.cpp — обгортка CLI.

Крок 1: task_store.hpp — тут усе чесно, без «магії»

// task_store.hpp
#pragma once

#include <string>
#include <vector>

namespace app {
    struct TaskStore {
        std::vector<std::string> tasks;

        void add_task(const std::string& text);
        void print_all() const;
    };
}

Тут жодних forward declaration не потрібно: ми зберігаємо std::vector<std::string> за значенням, отже заголовок зобовʼязаний включити <vector> і <string>. Заголовок самодостатній, сюрпризів немає.

Крок 2: task_store.cpp — реалізація

// task_store.cpp
#include "task_store.hpp"
#include <iostream>

namespace app {
    void TaskStore::add_task(const std::string& text) {
        tasks.push_back(text);
    }

    void TaskStore::print_all() const {
        for (const auto& t : tasks) {
            std::cout << "- " << t << '\n';
        }
    }
}

Крок 3: cli.hpp — тут forward declaration заощаджує залежності

// cli.hpp
#pragma once

#include <string>

namespace app {
    struct TaskStore; // попереднє оголошення

    void add_demo_tasks(TaskStore& store);
    void greet_user(const std::string& username);
}

Зверніть увагу: cli.hpp більше не тягне за собою <vector> і не підключає "task_store.hpp". Він знає лише, що TaskStore існує.

Крок 4: cli.cpp — підключаємо повне визначення, бо викликаємо методи

// cli.cpp
#include "cli.hpp"
#include "task_store.hpp"
#include <iostream>

namespace app {
    void add_demo_tasks(TaskStore& store) {
        store.add_task("Купити молоко");
        store.add_task("Написати код на C++");
    }

    void greet_user(const std::string& username) {
        std::cout << "Ласкаво просимо, " << username << "!\n"; // Ласкаво просимо, Bob!
    }
}

Крок 5: main.cpp — збираємо все разом

// main.cpp
#include "cli.hpp"
#include "task_store.hpp"

int main() {
    app::TaskStore store{};
    app::greet_user("Bob");
    app::add_demo_tasks(store);
    store.print_all();
}

Чому main.cpp включає і "cli.hpp", і "task_store.hpp"? Тому що main.cpp справді використовує обидва модулі. А от cli.hpp не зобовʼязаний включати "task_store.hpp", бо він не розкриває будову TaskStore — лише оголошує функції, які з ним працюватимуть.

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

4. Коли forward declaration не підходить

Тепер важливо не закохатися у forward declaration надто сильно. Це інструмент, а не релігія. Якщо почати вставляти struct X; усюди підряд, можна погіршити читабельність і отримати помилки «incomplete type», які спочатку сприймаються як «компілятор образився й пішов».

Найпростіший стоп-сигнал: якщо в заголовку ви хочете зберігати поле за значенням, вам потрібен повний тип.

Ось приклад, який виглядає невинно, але не скомпілюється:

// user.hpp
#pragma once

namespace app {
    struct Profile; // попереднє оголошення

    struct User {
        Profile profile; // не можна: Profile неповний
    };
}

Чому не можна? Тому що, щоб розмістити profile всередині User, компілятор зобовʼязаний знати, скільки байтів займає Profile. А він цього не знає.

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

// person.hpp
#pragma once

namespace app {
    struct Address; // попереднє оголошення

    struct Person {
        Address* address{};

        // помилка, якщо Address іще неповний:
        // std::string city() const { return address->city; }
    };
}

У такій ситуації потрібно або перенести реалізацію методу в .cpp, де ви підключите "address.hpp", або підключити "address.hpp" прямо в цей заголовок, якщо без цього ніяк.

5. Як читати помилки про incomplete type

Якщо ви лише починаєте, повідомлення компілятора про incomplete type зазвичай схожі на загадку, яку написав утомлений ельф на асемблері. Але добра новина в тому, що логіка там майже завжди однакова.

Коли компілятор пише щось на кшталт «invalid use of incomplete type» або «field has incomplete type», це майже завжди означає, що ви зробили forward declaration, але саме в цьому місці компілятору знадобилося знати розмір або поля типу.

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

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

6. Типові помилки під час використання forward declaration

Помилка № 1: forward declaration у неправильному namespace.
Це особливо підступно, бо код виглядає «майже правильно»: ви написали struct TaskStore;, а справжній TaskStore міститься в namespace app. У результаті у вас зʼявляються два різні типи з однаковим імʼям у різних просторах імен, і компілятор починає лаятися там, де ви цього взагалі не очікували. Лікується простою звичкою: оголошуйте forward declaration там само, де живе тип, тобто всередині потрібного namespace.

Помилка № 2: спроба зберігати неповний тип за значенням.
Щойно ви пишете X field;, компілятору потрібен розмір X. Forward declaration цього розміру не дає. Тому або підключайте заголовок із визначенням X, або змінюйте дизайн так, щоб в інтерфейсі були посилання чи вказівники, а деталі — у реалізації. Головне — не намагайтеся «вмовити компілятор»: у цій суперечці він однаково впертіший.

Помилка № 3: inline-реалізація в .hpp, яка лізе в поля неповного типу.
Дуже поширений сценарій: ви зробили struct A; і поле A* a;, а потім прямо в .hpp написали метод, який робить a->something. Але something невідоме, бо A іще неповний. Виправлення зазвичай просте: перенести реалізацію в .cpp і підключити там заголовок із визначенням A.

Помилка № 4: спроба замінити стандартні заголовки самим forward declaration.
Forward declaration працює для ваших типів (struct X;), але не замінює стандартні заголовки. Якщо ви використовуєте std::string в оголошенні, вам потрібен #include <string> у цьому .hpp. Надія на транзитивні залежності — це той самий шлях, де «ніби працює», доки хтось не посуне #include на один рядок вище.

Помилка № 5: заголовок перетворюється на «детектив», де все зрозуміло лише після стрибків по файлах.
Forward declaration зменшує залежності, але може погіршити читабельність: у заголовку зʼявляються загадкові struct X; struct Y; struct Z;, і новачок не розуміє, що це за типи й звідки вони взялися. Хороше правило балансу таке: використовуйте forward declaration там, де він справді заощаджує залежності, особливо між модулями, але не бійтеся звичайного #include, якщо він робить інтерфейс зрозумілішим і не роздуває проєкт.