자체 포함 헤더¶

헤더 파일은 자체 포함(self-contained)되어야 하며(자체적으로 컴파일 가능) .h로 끝나야 합니다. 포함을 위해 만들어진 비헤더 파일은 .inc로 끝나야 하며, 드물게 사용해야 합니다.

모든 헤더 파일은 자체 포함되어야 합니다. 사용자와 리팩토링 도구가 헤더를 포함하기 위해 특별한 조건을 준수할 필요가 없어야 합니다. 구체적으로, 헤더는 헤더 가드(header guards)를 가져야 하며 필요한 다른 모든 헤더를 포함해야 합니다.

헤더가 인라인 함수나 템플릿을 선언하고, 헤더의 클라이언트가 이를 인스턴스화할 경우, 인라인 함수와 템플릿은 헤더에 정의가 있어야 하며, 직접 정의하거나 포함하는 파일에 정의가 있어야 합니다. 이러한 정의를 별도로 포함되는 헤더(-inl.h) 파일로 옮기지 마세요. 이 관행은 과거에는 일반적이었지만 더 이상 허용되지 않습니다. 템플릿의 모든 인스턴스화가 하나의 .cc 파일에서 발생하는 경우(명시적이거나 정의가 해당 .cc 파일에만 접근 가능하기 때문), 템플릿 정의는 해당 파일에 유지할 수 있습니다.

포함되도록 설계된 파일이 자체 포함되지 않은 드문 경우가 있습니다. 이러한 파일들은 일반적으로 다른 파일의 중간과 같은 비정상적인 위치에 포함되도록 의도됩니다. 헤더 가드를 사용하지 않을 수 있으며, 필수 조건을 포함하지 않을 수 있습니다. 이러한 파일은 .inc 확장자로 명명하세요. 드물게 사용하고, 가능하면 자체 포함 헤더를 선호하세요.

이해하기 쉽게 설명하기¶

자체 포함 헤더란?¶

자체 포함(self-contained) 헤더란 다른 파일에 의존하지 않고도 독립적으로 컴파일할 수 있는 헤더 파일을 의미합니다. 즉, 해당 헤더 파일만 #include하면 필요한 모든 것이 준비되어 있어야 합니다.

왜 자체 포함이 중요한가?¶

자체 포함 헤더를 사용하면:

사용 편의성: 헤더를 포함할 때 어떤 순서로 포함해야 하는지, 어떤 다른 헤더를 먼저 포함해야 하는지 고민할 필요가 없습니다.
리팩토링 용이성: 리팩토링 도구가 헤더를 자유롭게 이동하거나 수정할 수 있습니다.
유지보수성: 헤더 파일 간의 의존 관계가 명확해져 코드베이스 관리가 쉬워집니다.

자체 포함 헤더의 요구사항¶

모든 헤더 파일은 다음 조건을 만족해야 합니다:

헤더 가드(header guards) 포함: 중복 포함을 방지하기 위해 헤더 가드를 반드시 포함해야 합니다.
필수 헤더 포함: 헤더에서 사용하는 모든 타입, 함수, 상수 등을 정의하는 헤더를 직접 포함해야 합니다. 다른 헤더가 포함해줄 것을 기대하지 마세요.

예시¶

// 좋은 예: 자체 포함 헤더
#ifndef MYPROJECT_WIDGET_H_
#define MYPROJECT_WIDGET_H_

#include <string>  // std::string을 사용하므로 직접 포함
#include <vector>  // std::vector를 사용하므로 직접 포함

class Widget {
  std::string name_;
  std::vector<int> data_;
};

#endif  // MYPROJECT_WIDGET_H_

// 나쁜 예: 자체 포함되지 않은 헤더
#ifndef MYPROJECT_WIDGET_H_
#define MYPROJECT_WIDGET_H_

// std::string과 std::vector를 사용하지만 포함하지 않음
// 다른 파일에서 이 헤더를 사용하려면 <string>과 <vector>를 먼저 포함해야 함
class Widget {
  std::string name_;  // 컴파일 오류 가능!
  std::vector<int> data_;
};

#endif  // MYPROJECT_WIDGET_H_

인라인 함수와 템플릿에 대해¶

헤더가 인라인 함수나 템플릿을 선언하고, 헤더를 사용하는 코드가 이를 인스턴스화할 경우, 인라인 함수와 템플릿의 정의도 헤더에 포함되어야 합니다. 정의는 직접 작성하거나, 포함하는 다른 헤더 파일에 있어야 합니다.

과거에는 이러한 정의를 별도의 -inl.h 파일로 분리하는 관행이 있었지만, 이제는 더 이상 허용되지 않습니다.

단, 템플릿의 모든 인스턴스화가 하나의 .cc 파일에서만 발생하는 경우(명시적 인스턴스화이거나 정의가 해당 .cc 파일에만 접근 가능한 경우), 템플릿 정의는 해당 .cc 파일에 유지할 수 있습니다.

예외: .inc 파일¶

드문 경우로, 자체 포함되지 않은 파일이 필요한 경우가 있습니다. 이러한 파일들은 일반적으로 다른 파일의 중간 같은 비정상적인 위치에 포함되도록 설계됩니다. 이러한 파일은:

헤더 가드를 사용하지 않을 수 있습니다.
필수 조건을 포함하지 않을 수 있습니다.
.inc 확장자를 사용해야 합니다.

.inc 파일은 가능한 한 드물게 사용하고, 대부분의 경우 자체 포함 헤더를 선호해야 합니다.