헤더 파일에는 무엇을 넣어야 하나요?

선언(declaration), 인라인 함수, 템플릿, 상수를 넣습니다. 정의(definition)는 소스 파일에 넣습니다.

#pragma once와 인클루드 가드 중 무엇을 써야 하나요?

#pragma once가 간결하지만 비표준입니다. 인클루드 가드가 표준이고 호환성이 좋습니다.

전방 선언은 언제 사용하나요?

포인터나 참조만 사용할 때 전방 선언을 사용하면 컴파일 시간을 단축할 수 있습니다.

C++ Header Files | "헤더 파일" 가이드

2026년 3월 12일 · 20분 읽기 · 수정 2026년 3월 29일 초급 튜토리얼

이 글의 핵심

C++ Header Files에 대한 실전 가이드입니다.

들어가며

C++에서 헤더 파일(.h, .hpp)은 선언(declaration)을 담는 파일입니다. 코드를 모듈화하고 재사용성을 높이는 핵심 요소입니다.

1. 헤더 파일 기본

선언 vs 정의

// math.h (헤더 파일 - 선언)
#ifndef MATH_H
#define MATH_H

int add(int a, int b);  // 선언 (declaration)
int subtract(int a, int b);

#endif

// math.cpp (소스 파일 - 정의)
#include "math.h"

int add(int a, int b) {  // 정의 (definition)
    return a + b;
}

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

// main.cpp (사용)
#include <iostream>
#include "math.h"

int main() {
    std::cout << add(3, 5) << std::endl;  // 8
    std::cout << subtract(10, 3) << std::endl;  // 7
}

선언 vs 정의 비교

구분	선언 (Declaration)	정의 (Definition)
위치	헤더 파일 (.h)	소스 파일 (.cpp)
역할	존재를 알림	실제 구현
중복	가능	불가능 (ODR 위반)
예시	`int add(int, int);`	`int add(int a, int b) { return a + b; }`

핵심 개념:

선언: 컴파일러에게 “이런 함수가 있다”고 알림
정의: 실제 구현 코드
ODR (One Definition Rule): 정의는 프로그램 전체에서 하나만

2. 인클루드 가드

중복 포함 문제

// myheader.h (가드 없음)
class MyClass {};

// main.cpp
#include "myheader.h"
#include "myheader.h"  // 중복 포함!

// 컴파일 에러: MyClass가 두 번 정의됨

인클루드 가드 사용

// myheader.h
#ifndef MYHEADER_H
#define MYHEADER_H

class MyClass {
public:
    void doSomething();
};

#endif  // MYHEADER_H

동작 원리:

첫 번째 포함: MYHEADER_H가 정의되지 않았으므로 내용 포함
두 번째 포함: MYHEADER_H가 이미 정의되어 있으므로 내용 건너뜀

#pragma once

// myheader.h
#pragma once

class MyClass {
public:
    void doSomething();
};

인클루드 가드 vs #pragma once

방식	장점	단점
`#ifndef`	표준, 호환성 좋음	코드가 길다, 매크로 이름 충돌 가능
`#pragma once`	간결, 빠름	비표준 (대부분 지원)

실전 팁:

개인 프로젝트: #pragma once (간결)
라이브러리: #ifndef (호환성)
둘 다 사용해도 됨 (중복 방지)

3. 실전 예제

예제 1: 기본 헤더

// calculator.h
#ifndef CALCULATOR_H
#define CALCULATOR_H

class Calculator {
public:
    int add(int a, int b);
    int subtract(int a, int b);
    int multiply(int a, int b);
    int divide(int a, int b);
    
private:
    int lastResult;
};

#endif

// calculator.cpp
#include "calculator.h"
#include <stdexcept>

int Calculator::add(int a, int b) {
    lastResult = a + b;
    return lastResult;
}

int Calculator::subtract(int a, int b) {
    lastResult = a - b;
    return lastResult;
}

int Calculator::multiply(int a, int b) {
    lastResult = a * b;
    return lastResult;
}

int Calculator::divide(int a, int b) {
    if (b == 0) {
        throw std::invalid_argument("0으로 나눌 수 없습니다");
    }
    lastResult = a / b;
    return lastResult;
}

// main.cpp
#include <iostream>
#include "calculator.h"

int main() {
    Calculator calc;
    
    std::cout << calc.add(10, 5) << std::endl;      // 15
    std::cout << calc.subtract(10, 5) << std::endl; // 5
    std::cout << calc.multiply(10, 5) << std::endl; // 50
    std::cout << calc.divide(10, 5) << std::endl;   // 2
}

예제 2: 템플릿 헤더

// stack.h
#ifndef STACK_H
#define STACK_H

#include <vector>
#include <stdexcept>

template<typename T>
class Stack {
private:
    std::vector<T> data;
    
public:
    void push(const T& value) {
        data.push_back(value);
    }
    
    T pop() {
        if (data.empty()) {
            throw std::runtime_error("스택이 비어있습니다");
        }
        T value = data.back();
        data.pop_back();
        return value;
    }
    
    const T& top() const {
        if (data.empty()) {
            throw std::runtime_error("스택이 비어있습니다");
        }
        return data.back();
    }
    
    bool empty() const {
        return data.empty();
    }
    
    size_t size() const {
        return data.size();
    }
};

#endif

// main.cpp
#include <iostream>
#include "stack.h"

int main() {
    Stack<int> intStack;
    intStack.push(1);
    intStack.push(2);
    intStack.push(3);
    
    std::cout << "Top: " << intStack.top() << std::endl;  // 3
    std::cout << "Pop: " << intStack.pop() << std::endl;  // 3
    std::cout << "Size: " << intStack.size() << std::endl; // 2
}

템플릿 헤더 규칙:

템플릿은 헤더에 전체 구현을 넣어야 함
컴파일러가 인스턴스화할 때 정의가 필요
소스 파일로 분리하면 링크 에러 발생

예제 3: 전방 선언

// window.h
#ifndef WINDOW_H
#define WINDOW_H

#include <string>

class Window {
public:
    Window(const std::string& title);
    void show();
    void hide();
};

#endif

// widget.h
#ifndef WIDGET_H
#define WIDGET_H

class Window;  // 전방 선언 (window.h 포함 불필요)

class Widget {
private:
    Window* window;  // 포인터만 사용
    
public:
    void setWindow(Window* w);
    Window* getWindow() const;
};

#endif

// widget.cpp
#include "widget.h"
#include "window.h"  // 여기서 포함

void Widget::setWindow(Window* w) {
    window = w;
}

Window* Widget::getWindow() const {
    return window;
}

전방 선언 장점:

컴파일 시간 단축
헤더 의존성 감소
순환 의존성 해결

예제 4: 인라인 함수

// utils.h
#ifndef UTILS_H
#define UTILS_H

#include <algorithm>

// 인라인 함수는 헤더에 정의 가능
inline int max(int a, int b) {
    return a > b ? a : b;
}

inline int min(int a, int b) {
    return a < b ? a : b;
}

inline int clamp(int value, int minVal, int maxVal) {
    return std::min(std::max(value, minVal), maxVal);
}

// 템플릿 인라인 함수
template<typename T>
inline T square(T value) {
    return value * value;
}

#endif

// main.cpp
#include <iostream>
#include "utils.h"

int main() {
    std::cout << max(10, 20) << std::endl;      // 20
    std::cout << min(10, 20) << std::endl;      // 10
    std::cout << clamp(15, 0, 10) << std::endl; // 10
    std::cout << square(5) << std::endl;        // 25
    std::cout << square(3.5) << std::endl;      // 12.25
}

4. 헤더에 넣을 수 있는 것

헤더 파일 구성

// mylib.h
#ifndef MYLIB_H
#define MYLIB_H

#include <string>
#include <vector>

// 1. 전역 상수 (inline 또는 constexpr)
inline constexpr int MAX_SIZE = 100;
constexpr double PI = 3.14159;

// 2. 타입 정의
using UserID = int;
using UserList = std::vector<std::string>;

// 3. 열거형
enum class Status {
    Success,
    Error,
    Pending
};

// 4. 클래스 선언
class MyClass {
public:
    void publicMethod();
    
private:
    int data;
};

// 5. 인라인 함수 정의
inline int square(int x) {
    return x * x;
}

// 6. 템플릿 정의
template<typename T>
T max(T a, T b) {
    return a > b ? a : b;
}

// 7. 함수 선언
void globalFunction();

// 8. extern 변수 선언
extern int globalCounter;

#endif

헤더 vs 소스 파일

항목	헤더 (.h)	소스 (.cpp)
클래스 선언	✅	❌
함수 선언	✅	❌
함수 정의	❌ (예외: inline, template)	✅
전역 변수 선언	✅ (`extern`)	❌
전역 변수 정의	❌	✅
상수	✅ (`constexpr`, `inline`)	✅
인라인 함수	✅	✅
템플릿	✅	❌

5. 자주 발생하는 문제

문제 1: 중복 정의 (ODR 위반)

// ❌ 헤더에 변수 정의
// myheader.h
int globalVar = 10;  // 여러 cpp에서 포함하면 중복 정의!

// ✅ 선언만 (헤더)
// myheader.h
extern int globalVar;

// 정의 (소스)
// myheader.cpp
int globalVar = 10;

// ✅ 또는 inline 사용 (C++17)
// myheader.h
inline int globalVar = 10;

에러 메시지:

error: multiple definition of 'globalVar'

문제 2: 순환 인클루드

// ❌ 순환 의존성
// a.h
#ifndef A_H
#define A_H
#include "b.h"

class A {
    B* b;  // B의 전체 정의 필요
};
#endif

// b.h
#ifndef B_H
#define B_H
#include "a.h"

class B {
    A* a;  // A의 전체 정의 필요
};
#endif

// ✅ 전방 선언으로 해결
// a.h
#ifndef A_H
#define A_H

class B;  // 전방 선언

class A {
    B* b;  // 포인터만 사용
};
#endif

// b.h
#ifndef B_H
#define B_H

class A;  // 전방 선언

class B {
    A* a;
};
#endif

문제 3: 불필요한 인클루드

// ❌ 모든 헤더 포함 (컴파일 시간 증가)
// myclass.h
#include <iostream>
#include <vector>
#include <map>
#include <algorithm>
#include <string>
// 실제로는 string만 사용

// ✅ 필요한 것만 포함
// myclass.h
#include <string>

class MyClass {
    std::string name;
};