【C++】コメントの書き方入門｜1行・複数行・Doxygenから保守性を高める最新作法まで

2026年2月6日

言語仕様・基本文法

C++を用いたシステム開発において、ソースコードの可読性を保つことはプロジェクトの成功を左右する非常に重要な要素です。

プログラムはコンピュータが実行するものですが、そのコードを読み、修正し、機能を追加するのは人間です。

コメントを適切に活用することで、自分自身やチームメンバーが「なぜこの処理が必要なのか」を即座に理解できるようになります。

本記事では、C++における基本的なコメントの書き方から、Doxygenを用いたドキュメント生成、さらには保守性を極限まで高めるための最新の作法まで、プロフェッショナルな視点で詳しく解説します。

目次 [ close ]

C++におけるコメントの基本

C++には、大きく分けて「単一行コメント」と「複数行コメント」の2種類が存在します。

これらは用途に応じて使い分けることが一般的です。

単一行コメント (//)

単一行コメントは、スラッシュを2つ重ねた // 以降からその行の末尾までをコメントとして扱う形式です。

C言語の拡張としてC++に導入されましたが、現在では最も頻繁に使われる形式です。

C++

#include <iostream>

int main() {
    // 標準出力にメッセージを表示します
    std::cout << "Hello, C++ World!" << std::endl;

    int speed = 100; // 変数の宣言と同時に説明を記述することも可能です
    return 0;
}

この形式は、特定のコード行に対する短い説明や、一時的な処理の無効化（コメントアウト）に適しています。

複数行コメント (/* … */)

複数行コメントは、 / で始まり / で終わる範囲をすべてコメントとする形式です。

行をまたいで長い解説を記述する場合に使用されます。

C++

/*
 このプログラムは、C++のコメント機能を
 デモンストレーションするためのサンプルです。
 複数行にわたる詳細な仕様などを記述する際に便利です。
 */
#include <iostream>

int main() {
    /* 
       ブロック単位で処理を
       コメントアウトすることもできます。
    */
    std::cout << "Block comment example" << std::endl;
    return 0;
}

複数行コメントの注意点

複数行コメントを使用する際の最大の注意点は、コメントをネスト（入れ子）にすることができないという点です。

以下のコードはコンパイルエラーとなります。

C++

/*
  外側のコメント
  /* 内側のコメント */
  ここでエラーが発生します。最初の "*/" で外側のコメントも閉じられたとみなされるためです。
*/

このような問題を避けるため、広範囲のコードを一時的に無効化する場合は、後述するプリプロセッサ命令の使用が推奨されます。

実践的なコメントの使い分け

単に文法を知っているだけでは、保守性の高いコードは書けません。

状況に応じた最適なコメント技術を使い分ける必要があります。

プリプロセッサによるコメントアウト (#if 0)

大規模なコードブロックを一時的に無効化したい場合、 /* ... */ を使うと、その中に既に複数行コメントが含まれていた場合に構文エラーが発生します。

これを防ぐために、プロフェッショナルの現場では #if 0 と #endif が多用されます。

C++

#include <iostream>

int main() {
    std::cout << "Running..." << std::endl;

#if 0
    // このブロック全体がコンパイル対象から外れます。
    // 内部に /* ... */ があっても問題ありません。
    std::cout << "This part is disabled." << std::endl;
    /* 既存のコメント */
#endif

    return 0;
}

この手法は、デバッグ中に特定の機能を切り離す際に非常に安全で確実な方法です。

文末コメントの活用と整列

変数の意味を説明する場合、行の右側にコメントを記述することがあります。

この際、タブやスペースを用いて開始位置を揃えると、視認性が大幅に向上します。

変数名	意味	単位
`max_health`	最大体力	ポイント
`current_speed`	現在の移動速度	m/s
`retry_count`	再試行回数	回

C++

int max_hp = 100;      // プレイヤーの最大体力
int current_hp = 80;   // 現在の体力（0以下でゲームオーバー）
double velocity = 5.5; // 移動速度（秒速）

Doxygenによるドキュメント自動生成

モダンなC++開発において、関数やクラスの仕様をコメントとして記述し、それをツールでドキュメント化（HTMLやPDFなど）する手法は標準的です。

その代表格が Doxygen です。

Doxygen形式の書き方

Doxygenでは、通常のコメントに特殊な記号を加えることで、ドキュメント生成対象として認識させます。

一般的には /** ... */ または /// を使用します。

C++

/**
 @file MathUtils.hpp
 @brief 数学的なユーティリティ関数を提供するヘッダー
 */

/**
 @brief 2つの数値の合計を計算します。
 
 @param a 1つ目の数値
 @param b 2つ目の数値
 @return int 計算された合計値
 @note 引数が負数の場合でもそのまま加算されます。
 */
int add(int a, int b) {
    return a + b;
}

主要なDoxygenコマンド

Doxygenで使用される主なタグは以下の通りです。

これらを活用することで、引数の意味や戻り値の型、例外の有無などを明確に示すことができます。

@brief：簡単な説明
@param：引数の説明
@return：戻り値の説明
@throw：スローされる例外の説明
@details：詳細な解説
@see：関連する関数やクラスへの参照

このように記述されたコードは、後からツールを実行するだけで、ブラウザで閲覧可能なリファレンスマニュアルへと変換されます。

保守性を高めるための最新作法

コメントは多ければ良いというものではありません。

むしろ、不適切なコメントはコードの変更に追従できず、嘘の情報となって開発を混乱させる原因になります。

最新のC++開発における「良いコメント」の考え方を整理します。

「何をしているか」ではなく「なぜしているか」を書く

優れたコードは、その構造自体が「何をしているか」を語るべきです（自己文書化）。

そのため、コメントにはコードからは読み取れない「意図」や「背景」を記述することが推奨されます。

避けるべき例：

C++

// iを0から10まで増やす
for (int i = 0; i < 10; ++i) {
    // ...
}

※コードを見ればわかるため、このコメントは不要です。

推奨される例：

C++

// 通信リトライが規定回数（10回）を超えると、
// ネットワーク切断と判断して例外を投げる仕様に基づいたループ
for (int i = 0; i < MAX_RETRY; ++i) {
    // ...
}

※なぜ10回なのか、失敗した時に何が起きるのかという「意図」が明確です。

自己文書化コード（Self-Documenting Code）の推進

コメントを書く前に、「変数名や関数名を工夫することでコメントを不要にできないか」を検討してください。

C++

// 悪い例：コメントがないと意味がわからない
double d = 86400; // 1日の秒数

// 良い例：名前だけで意味が伝わる
const double seconds_per_day = 86400;

このように、適切な命名を行うことで、コメントを減らしつつ可読性を高めることができます。

特殊なコメントマーカー

チーム開発において、後で修正が必要な箇所や改善点を示すために、特定のキーワードを用いたコメント（アノテーション）が使われます。

TODO: あとで実装する予定の機能。
FIXME: 既知のバグがあるが、とりあえず動いている箇所。修正が必要。
HACK: あまり綺麗ではない解法を使っている箇所。リファクタリングの対象。
XXX: 注意が必要な箇所。議論の余地がある設計。

C++

// TODO: 次のリリースまでにメモリリークの可能性を調査する
// FIXME: この処理は特定の条件下で負数を返すバグがある
void process_data() {
    // ...
}

多くのIDE（統合開発環境）では、これらのキーワードを抽出して一覧表示する機能を持っています。

現代的なC++機能とコメントの代替

C++の進化に伴い、従来はコメントで補足していた情報を言語仕様として明示できるようになりました。

これにより、コンパイラによるチェックが可能になり、より安全なコードが書けます。

属性（Attributes）の活用

C++11以降、角括弧 [[ ... ]] を用いた属性指定が可能になりました。

これは「コメントによる注意喚起」を「コンパイラへの命令」に変換するものです。

[[nodiscard]]

関数の戻り値を無視してはいけない場合に指定します。

C++

[[nodiscard]] int calculate_important_value() {
    return 42;
}

int main() {
    calculate_important_value(); // コンパイラが警告を出してくれる
    return 0;
}

[[deprecated]]

その関数やクラスが非推奨であることを示します。

単にコメントで「使わないでください」と書くよりも強力です。

C++

[[deprecated("Use new_function() instead.")]]
void old_function() {}

int main() {
    old_function(); // コンパイル時に警告メッセージが表示される
    return 0;
}

static_assert による「コードの前提」の記述

「この変数は必ず正の数でなければならない」といった前提条件をコメントに書く代わりに、 static_assert を使うことで、コンパイル時にその条件をチェックできます。

C++

template <typename T>
void process(T value) {
    static_assert(sizeof(T) >= 4, "T must be at least 32-bit.");
    // ...
}

チーム開発におけるコメント規約の重要性

プロジェクトが大きくなるにつれ、開発者ごとにコメントの書き方が異なると、全体の統一感が失われます。

以下のポイントを「コーディング規約」として定めておくことが推奨されます。

言語の統一：日本語で書くのか、将来のグローバル展開を見据えて英語で書くのかを決定します。
Doxygenの必須化：公開API（ヘッダーファイル）には必ずDoxygen形式のコメントを付けるといったルールを設けます。
コメントの鮮度：コードを修正した際、関連するコメントも必ず更新することを徹底します。
不要なコメントの削除：古いコードをコメントアウトしたまま放置せず、バージョン管理システム（Gitなど）を信頼して削除します。

コメントの量と質のバランス

プロジェクトにおけるコメントの理想的な割合については諸説ありますが、重要なのは「複雑なアルゴリズムの解説」や「ビジネスロジックの背景」にリソースを割くことです。

単純なゲッターやセッターに対して「値を返します」といった自明なコメントを付ける必要はありません。

C++

// 悪い例：自明すぎるコメント
class User {
public:
    // 名前を取得します
    std::string get_name() const { return name; }
private:
    std::string name; // ユーザーの名前
};

このような冗長な記述を減らすことで、本当に重要なコメントが埋もれてしまうのを防ぐことができます。

まとめ

C++におけるコメントは、単なるプログラムの補足説明ではありません。

それは開発者間のコミュニケーションツールであり、将来の自分へのメッセージでもあります。

基本： // は日常的な説明に、 /* ... */ は広範囲の説明に使用します。
管理：大規模なコメントアウトには #if 0 を活用してエラーを防ぎます。
自動化：Doxygen形式を採用し、常に最新の仕様書をコードから生成できる体制を整えます。
設計：コメントを書く前に「名前」で説明できないか検討し、コードの意図（Why）を記述することに集中します。
最新機能： [[nodiscard]] や static_assert を活用し、コメントの役割を言語機能に肩代わりさせます。

「読みやすいコードは、書かれたコメントの数ではなく、書かれたコメントの質によって決まる」という原則を忘れずに、日々の開発に取り組んでいきましょう。

適切にメンテナンスされたコメントは、ソフトウェアの寿命を延ばし、バグの混入を防ぐ最強の武器となります。