【C言語】インクルードガードの正しい書き方とNG例まとめ

2025年10月18日2025年12月8日

C言語

C言語で少し大きめのプロジェクトを書き始めると、必ずぶつかるのがヘッダファイルの多重インクルード問題です。

これを防ぐための仕組みがインクルードガードです。

本記事では、インクルードガードの正しい書き方とNG例を、図解とサンプルコードを交えながら丁寧に解説します。

pragma onceとの違いや、プロジェクトでの運用ルール作りまで一気に整理していきます。

目次 [ close ]

インクルードガードとは

インクルードガードの役割と必要性

インクルードガードとは、ヘッダファイルが同じ翻訳単位(コンパイル単位)の中で複数回読み込まれても、内容を1回だけ有効にするための仕組みです。

C言語では#includeを使ってヘッダファイルを読み込みますが、ヘッダが別のヘッダからもインクルードされていると、結果として同じヘッダが何度も読み込まれることがあります。

インクルードガードがないと、次のようなエラーを引き起こします。

構造体や列挙体のredefinitionエラー
グローバル変数や関数プロトタイプの二重定義扱い
typedefの再定義エラー

典型的な例を1つ示します。

C言語

/* file: common.h */
typedef struct {
    int id;
    const char *name;
} User;

/* 他にもいろいろ定義があると仮定 */

C言語

/* file: a.h */
#include "common.h"

/* Aモジュール用の宣言 */
void func_a(User *u);

C言語

/* file: b.h */
#include "common.h"

/* Bモジュール用の宣言 */
void func_b(User *u);

C言語

/* file: main.c */
#include "a.h"
#include "b.h"

int main(void) {
    return 0;
}

この構成ではmain.cから見るとcommon.hが2回インクルードされる形になります。

その結果、多くの処理系では次のようなエラーになります。

common.h:3:3: error: redefinition of ‘User’

インクルードガードは、このような「同じヘッダが複数回インクルードされる状況」を想定してあらかじめ防御するための、お決まりの書き方だと理解すると分かりやすいです。

pragma onceとの違いと注意点

インクルードガードとよく比較されるのが#pragma onceです。

どちらも目的はヘッダの多重インクルード防止ですが、性質が異なります。

include guard(インクルードガード)の特徴

標準C言語に含まれる仕組みです。
#ifndef / #define / #endifでマクロを使って実現します。
ほぼすべてのCコンパイラ・環境で同じように動作します。
書くのが少しだけ冗長ですが、移植性が高く、安全です。

#pragma once の特徴

非標準のコンパイラ拡張です。
1行書くだけでよいので、とても簡潔です。

C言語

#pragma once

/* このヘッダファイルの中身 */

多くのメジャーなコンパイラ(gcc、clang、MSVCなど)でサポートされています。
ただし一部の古いコンパイラや特殊環境では動かない可能性があります。

どちらを使うべきか

移植性が強く求められるライブラリや組込み系のプロジェクトでは、今でもマクロを用いたインクルードガードを基本とすることが多いです。

一方、特定コンパイラに固定されたプロジェクトであれば#pragma onceを使う選択肢も現実的です。

本記事では、標準的でどこでも通用する「マクロを使ったインクルードガード」の書き方に焦点を当てて解説していきます。

インクルードガードの正しい書き方

基本的なインクルードガードの書き方

最も基本的なインクルードガードの形は、次のようになります。

C言語

/* file: sample.h */

#ifndef SAMPLE_H      /* まだ SAMPLE_H が定義されていない場合のみ、このヘッダを有効にする */
#define SAMPLE_H      /* SAMPLE_H マクロを定義して、「読み込んだ」ことを記録する */

/* ヘッダファイルの中身(宣言など) */
void sample_function(void);

#endif /* SAMPLE_H */ /* SAMPLE_H が定義されている場合は、中身をスキップする */

処理の流れを文章で追うと次のようになります。

最初の#ifndef SAMPLE_Hで、SAMPLE_Hマクロが未定義なら、この先をコンパイル対象にします。
#define SAMPLE_Hでマクロを定義し、「この翻訳単位では、このヘッダはすでに読み込んだ」と印を付けます。
ヘッダの本体(関数や構造体の宣言)が続きます。
#endifまでの範囲が、インクルードガードで守られた領域になります。
同じ翻訳単位内で再度#include "sample.h"された場合は、すでにSAMPLE_Hが定義済みなので、#ifndefのブロック全体がスキップされます。

ヘッダファイルの先頭から末尾までを、まるごとインクルードガードで囲むのが基本形です。

マクロ名の付け方

インクルードガードのマクロ名は、ヘッダファイルを一意に識別できる名前にすることが重要です。

代表的なパターンをいくつか見てみます。

シンプルな例

C言語

/* user.h */
#ifndef USER_H
#define USER_H

typedef struct {
    int id;
} User;

#endif /* USER_H */

単純にファイル名を大文字にして_Hを付けています。

ディレクトリを含めた例

同じプロジェクト内でutil/logger.hとnet/logger.hのように、ファイル名が同じだが配置ディレクトリが異なるヘッダが存在することはよくあります。

この場合、単にLOGGER_Hとすると重複する可能性が高くなります。

そこで、プロジェクト名やパスを含めて次のようにするのが一般的です。

C言語

/* project名: MYAPP、ファイル: net/logger.h */
#ifndef MYAPP_NET_LOGGER_H
#define MYAPP_NET_LOGGER_H

/* 宣言など */

#endif /* MYAPP_NET_LOGGER_H */

プロジェクトやチームによってルールは異なりますが、よく使われる構成は次のようなイメージです。

先頭にプロジェクト名(すべて大文字)
サブディレクトリ名を大文字にして_で連結
最後にファイル名(拡張子なし)を大文字で付ける
終端に_Hまたは_H_INCLUDEDを付ける

大文字・アンダースコアを使う理由

インクルードガードのマクロ名には、大文字とアンダースコアのみを使うことがほとんどです。

これにはいくつか理由があります。

1. 一目で「マクロ」と分かる

C言語では、大文字 + アンダースコアという書き方はマクロ名のスタイルとして広く定着しています。

コードを読んだときに「これは変数や関数ではなくマクロだ」と直感的に分かる
ツールやエディタのハイライトとも相性がよい

2. 予約語・識別子との衝突を避けやすい

C言語の規格では、先頭に_が付く識別子の一部は実装(コンパイラや標準ライブラリ)が自由に使ってよい予約領域とされています。

特に先頭が__の識別子や、先頭が_で次が大文字の識別子は避けなければなりません。

NGな例:

C言語

#ifndef _USER_H   /* 先頭が '_' + 大文字で、実装側と衝突する可能性がある */
#define _USER_H

#endif /* _USER_H */

先頭にアンダースコアを付けない大文字スタイルにすると、この種の問題を避けやすくなります。

3. 一貫性と自動生成のしやすさ

大文字・アンダースコアだけのルールにしておくと、エディタのスニペットや自動生成ツールで簡単に規則に沿ったマクロ名を作れるという利点もあります。

ヘッダファイル1つに1つのインクルードガードを定義する

インクルードガードは、基本的にヘッダファイル1つにつき1つ定義します。

つまり、ヘッダの先頭でガードを開始し、末尾で閉じる形です。

避けるべき書き方として、ヘッダの一部だけにガードをかける書き方があります。

C言語

/* file: bad.h */
/* これはアンチパターンの例 */

#ifndef BAD_PART_H
#define BAD_PART_H
int func_a(void);
#endif

int func_b(void);   /* ここはガードの外で、二重定義のリスクが残っている */

このような部分的なガードは、「なぜその部分だけを守るのか」を明確に説明できる特別な事情がない限り避けるべきです。

基本方針としては次のように覚えておくとよいです。

「ヘッダの先頭から末尾までを、1つのインクルードガードで丸ごと囲む」

インクルードガードのNG例とよくある間違い

マクロ名の重複によるバグ例

異なるヘッダファイルで、同じインクルードガードのマクロ名を使ってしまうと、非常に分かりにくいバグに繋がります。

C言語

/* file: user.h */
#ifndef COMMON_H      /* ◀ これ */
#define COMMON_H

typedef struct {
    int id;
} User;

#endif /* COMMON_H */

C言語

/* file: product.h */
#ifndef COMMON_H      /* ◀ こっちも同じ */
#define COMMON_H

typedef struct {
    int id;
} Product;

#endif /* COMMON_H */

C言語

/* file: main.c */
#include "user.h"
#include "product.h"   /* product.h の中身がスキップされる */

int main(void) {
    Product p;       /* Product が宣言されていない扱いになる */
    return 0;
}

この場合、user.hをインクルードした時点でCOMMON_Hが定義されてしまうため、その後にインクルードされるproduct.hの本体部分はすべてスキップされてしまいます。

コンパイル時には「Productが未定義」というエラーになるため、「なぜproduct.hの内容が無視されているのか」に気付きにくいのが厄介なところです。

この種のバグを防ぐには、プロジェクト内で絶対にかぶらない命名規則を決めることが重要です(後述のベストプラクティスで詳述します)。

ファイル名変更時にガード名を変え忘れるケース

プロジェクトの途中でヘッダファイル名を変更したのに、インクルードガードのマクロ名を修正し忘れることもよくあります。

C言語

/* もともとは config.h だったが、ファイル名だけ app_config.h に変更された例 */

/* file: app_config.h */
#ifndef CONFIG_H      /* ◀ 旧ファイル名のまま */
#define CONFIG_H

/* 設定関連の宣言 */

#endif /* CONFIG_H */

単体ではこの状態でも動きますが、将来的に別のconfig.hが追加されたときに、先ほどの「マクロ名の重複バグ」と同じ問題を引き起こす原因となります。

この問題を防ぐには、次のような習慣が有効です。

ファイル名を変えたら、同時にインクルードガード名も変える
エディタのリネーム機能で#ifndefと#endifのコメントも一括で更新する
コードレビュー時に「ヘッダ名とインクルードガード名の整合性」をチェックする

条件付きコンパイルとインクルードガードの誤用

条件付きコンパイル#if / #ifdef / #ifndefとインクルードガードを混ぜて複雑に書いてしまうと、意図しない挙動になりがちです。

やってしまいがちな誤用例:

C言語

/* file: debug.h - 悪い例 */

#ifdef DEBUG             /* ◀ DEBUG が定義されているときだけヘッダを有効にしたい */
#ifndef DEBUG_H
#define DEBUG_H

void debug_log(const char *msg);

#endif /* DEBUG_H */
#endif /* DEBUG */

この書き方だと、DEBUGが定義されていない翻訳単位では、debug_logの宣言そのものが存在しないことになります。

結果として、翻訳単位ごとに関数宣言の有無が変わるため、リンク時に関数のシンボル解決で問題になることがあります。

より安全な書き方は、インクルードガードでヘッダの存在自体を守り、その内部で条件付きコンパイルを行うやりかたです。

C言語

/* file: debug.h - より良い例 */

#ifndef MYAPP_DEBUG_H
#define MYAPP_DEBUG_H

#ifdef DEBUG      /* ◀ 内側で条件付きコンパイルを行う */
void debug_log(const char *msg);
#else
/* DEBUG 無効時もシンボルを用意しておくと、呼び出しコードを書きやすい */
static inline void debug_log(const char *msg) {
    (void)msg;    /* 何もしない */
}
#endif /* DEBUG */

#endif /* MYAPP_DEBUG_H */

こうすることで、どの翻訳単位でもdebug_logという名前は必ず存在し、その中身だけが変化するようにできます。

インクルードガードの書き忘れ・閉じ忘れの例

ヘッダファイルを書き足していくうちに、インクルードガードの#endifを書き忘れてしまうことがあります。

特にヘッダの末尾付近にコードを後から追加したときに起こりがちです。

C言語

/* file: forgotten.h - 悪い例 */

#ifndef FORGOTTEN_H
#define FORGOTTEN_H

int func_a(void);

/* ここからあとで追加したコード */
int func_b(void);

/* 本来ここに #endif が必要だが、書き忘れている */

このような場合、プリプロセッサは#endifが現れるまでずっとインクルードガードの範囲だと解釈します。

そのため、別のヘッダファイルやソースファイルの一部までガードの中に入ってしまい、思わぬコンパイルエラーを引き起こすことがあります。

防止策としては、次のような工夫が有効です。

#endif に対応するマクロ名をコメントで書く
- 例: #endif /* MYAPP_USER_H */
コードフォーマッタや静的解析ツールでプリプロセッサの対応関係をチェックする
インクルードガードの雛形をスニペット化し、コピペせずに使う

#pragma onceとの併用はNGか

一部のプロジェクトでは、次のように#pragma onceとインクルードガードを併用しているコードを見ることがあります。

C言語

#pragma once

#ifndef MYAPP_USER_H
#define MYAPP_USER_H

/* 宣言など */

#endif /* MYAPP_USER_H */

結論から言うと、技術的には両方書いても大きな問題は起こりません。

コンパイラによっては、pragma once のおかげでファイルシステムのアクセスが減り、ビルドが若干高速になることもあります。

ただし、運用面では次の点を考慮する必要があります。

コードを読む側からすると、「どちらが本当に必要なのか」が分かりにくい
チームでスタイルを統一しづらくなる
#pragma onceをサポートしないコンパイラでは、インクルードガード側だけが機能する

そのため、プロジェクトとして「どちらを公式スタイルにするか」を決めて、ヘッダごとにブレないようにするのが望ましいです。

多くの保守性重視のプロジェクトでは、次のような方針がよく採用されています。

基本はインクルードガード(マクロ)
特定コンパイラ前提であっても、pragma once だけに頼らずインクルードガードも書いておく
もしくは「pragma once を使わない」と明示的に決めて、コードをシンプルに保つ

インクルードガード運用のベストプラクティス

プロジェクト共通ルール(命名規則)を決める

インクルードガードは、プロジェクト内で一貫した命名規則を決めておくことで、重複やミスを大幅に減らすことができます。

例として、次のようなルールを定めることが考えられます。

すべて大文字、単語区切りは_
先頭にプロジェクト名を付ける(例: MYAPP_)
パスの/は_に置き換える
ファイル拡張子は除去し、最後に_Hを付ける

サンプルとして、ディレクトリ構造とマクロ名の対応表を見てみます。

ファイルパス	インクルードガード名
src/user.h	MYAPP_USER_H
src/net/socket.h	MYAPP_NET_SOCKET_H
src/net/http/client.h	MYAPP_NET_HTTP_CLIENT_H
include/myapp/config.h	MYAPP_CONFIG_H

このようなルールをコーディング規約として文書化しておくと、新しく参加したメンバーも迷わずに書けます。

自動生成スニペットやテンプレートの活用

人間が毎回手作業でインクルードガードを書くと、どこかで入力ミスや書き忘れが起こります。

そこで、エディタやIDEのスニペット機能を使って、ヘッダの雛形を自動挿入するのがおすすめです。

例えば、VS CodeやVim、Emacsなどでは「hdr」というショートカットを入力すると、次のようなテンプレートが展開されるように設定できます。

C言語

#ifndef ${GUARD_NAME}
#define ${GUARD_NAME}

/* ${FILENAME} の宣言をここに書く */

#endif /* ${GUARD_NAME} */

多くのエディタではカレントファイル名から自動的にGUARD_NAMEを生成するスクリプトも書けます。

例えば、ファイル名user.hならMYAPP_USER_Hを自動生成する、といった具合です。

この仕組みを取り入れることで、

毎回同じ形のインクルードガードになる
閉じ忘れやタイプミスを防ぎやすくなる
レビュー時の指摘事項が減り、本質的なロジックに集中できる

といったメリットがあります。

既存コードのインクルードガードをリファクタリングするコツ

既に大きくなってしまった既存プロジェクトでは、インクルードガードがバラバラな状態で放置されていることが多いです。

このような場合のリファクタリングは、一気に直そうとせず、段階的に進めるのがコツです。

1. 現状把握とルール決定

まずは次の点を洗い出します。

どのファイルがインクルードガードを持っていないか
ガード名が重複していそうなヘッダはどれか
pragma once が使われているヘッダはどれか

その上で、先ほど示したように今後採用する命名規則を明確に決めます。

2. 自動置換と半自動化

次に、スクリプトや正規表現を使って半自動的にガード名を統一します。

例えば、Pythonやシェルスクリプトを使って、ファイルパスから新しいガード名を計算し、ヘッダ内の#ifndefや#defineの行を書き換えることができます。

簡易的な例として、次のような擬似コードを考えてみます。

1. 全ヘッダファイル(.h)を列挙する
2. 各ファイルについて:
   a. ファイルパスから GUARD_NAME を生成(MYAPP_..._H 形式)
   b. 先頭の #ifndef/#define を探して置き換える
   c. 末尾の #endif コメントも更新する
3. ビルドしてコンパイルエラーが出ないか確認する

この処理自体は各プロジェクトの構成に依存するため、実際には自分たちの環境に合うスクリプトを書く必要があります。

3. 静的解析やビルドで検証する

リファクタリング後は、次のような方法で問題がないか確認します。

全ターゲット・全構成でフルビルドを行う
可能であれば重複マクロ名やヘッダガードの欠落を検出できる静的解析ツールを導入する
コードレビューで新規ヘッダのガード名を必ずチェックする

段階的に進めていけば、大規模な既存コードベースでも、安全にインクルードガードを整備することが可能です。

まとめ

インクルードガードは、C言語のヘッダ設計において必須とも言える基本テクニックです。

多重インクルードによる再定義エラーを防ぎ、プロジェクト全体を安定してビルドできる土台になります。

マクロ名の付け方や、1ヘッダ1ガードという原則を守ることで、思わぬバグを避けられます。

また、pragma once との使い分けや、命名規則・スニペットなどの運用ルールを整えることで、チーム開発でも迷いなくヘッダを書けるようになります。

今日紹介したポイントを自分のプロジェクトに取り入れ、ヘッダ周りのトラブルを未然に防いでいきましょう。