コメント | Programming Place Plus　新C++編

このページの概要

このページでは、コメントという機能を取り上げます。これまでに取り上げてきた機能とちがって、コメントはプログラムの実行結果には何ら影響を与えません。コメントは、ソースコードを書いたり読んだりする人間に向けた機能です。

以下は目次です。要点だけをさっと確認したい方は、「まとめ」をご覧ください。

• コメント
• // によるコメント
• /* ～ */ によるコメント
  • 行の一部だけをコメントアウトする
  • 複数行をまとめてコメントアウトする
• 文字列リテラル内のコメント記号
• コメントに書くこと・書かないこと
• まとめ
• 練習問題
• 参考リンク
• 更新履歴

コメント

人間がソースコードに書かれている内容を読み解くとき、変数や constexpr変数につけられた名前（識別子）が助けになります。

しかし、あまりにも長くて説明的な名前は、かえって読みづらいソースコードになってしまいますし、使える文字の制約（「定数式と識別子」のページを参照）もありますから、限界があります。

そこで、より直接的に、しかも日本語などの人間が読みやすい言語を使った説明やメモをソースコード内に書き込む方法があります。このような説明文やメモのことを、コメント（注釈）(comment) と呼びます。

コメントはソースコードに書き込みますが、コンパイル時にコメントの部分は無視されます。そのため、プログラムの動作に影響を与えません。

【上級】正確には、コメントはコンパイルに先だって１つの空白文字に置き換えられます。

プログラマーが書き込んだコメントを、コンパイラにコメントであるとみなしてもらうには、正しい記法で書く必要がありますが、内容自体は好きにできます。

コメントには、この後紹介する２つの記法があります。２つの記法がソースファイル内に混在してあらわれても問題ありません。

// によるコメント

１つ目は、// のように２つのスラッシュを並べて書き、その後ろにメモを記述する方法です。/ は除算で使う記号と同じですが、２つ並べるとコメントの記号になるということです。

この記法では、その行の終わりまでがコメントと認識されます。

実際のプログラムの例は次のようになります。「文字列の入力」のページで登場したプログラムにコメントを追加してみます。

#include <iostream>
#include <string>

int main()
{
    // 整数の入力を受け取って、そのまま出力する
    std::cout << "Please enter an integer.\n";
    int value {};
    std::cin >> value;
    std::cin.ignore();  // 最後に入力されてしまう改行文字を無視する
    std::cout << value << "\n";

    // 文字列の入力を受け取って、そのまま出力する
    // 空白を含んだ文字列でも受け取れるように、std::getline関数を使っている
    std::cout << "Please enter a string.\n";
    std::string s {};
    std::getline(std::cin, s);
    std::cout << s << "\n";
}

実行結果：

Please enter an integer.
100   <-- 入力した整数。最後に Enterキーを押している
100
Please enter a string.
abc   <-- 入力した文字列。最後に Enterキーを押している
abc

コメントを記述する場所は自由です。あるコメントが、ソースファイル内のどの部分の説明やメモになっているのかが分かりやすいようにしましょう。

たとえば、ある１つの文に対するコメントなら、その行の上側や右側に書きます。サンプルプログラムでは、std::cin.ignore(); に対するコメントがその例です。

また、複数の文からなるコードに対するコメントは、そのまとまりの上側に書きます。「// 整数の入力を受け取って～」や「// 文字列の入力を受け取って～」がこれに当たります。説明が長くなるなら、コメントを複数行に渡って書きます。横に長くなることを受け入れて、１行に書いてしまう手もありえますが、右側にスクロールしないと全容が把握できなくなる恐れがあり、読み手に対して不親切です。

/* ～ */ によるコメント

コメントの書き方の２つ目は、/* と */ という２文字の記号のペアを使う方法です。この記法では、このペアで挟まれた範囲にメモを記述します。

【Ｃ言語プログラマー】Ｃ言語に古くからあるコメントスタイルと同じものです。

この方法では、次のように記述します。

#include <iostream>
#include <string>

int main()
{
    /* 整数の入力を受け取って、そのまま出力する */
    std::cout << "Please enter an integer.\n";
    int value {};
    std::cin >> value;
    std::cin.ignore();  /* 最後に入力されてしまう改行文字を無視する */
    std::cout << value << "\n";

    /* 文字列の入力を受け取って、そのまま出力する
       空白を含んだ文字列でも受け取れるように、std::getline関数を使っている */
    std::cout << "Please enter a string.\n";
    std::string s {};
    std::getline(std::cin, s);
    std::cout << s << "\n";
}

実行結果：

Please enter an integer.
100   <-- 入力した整数。最後に Enterキーを押している
100
Please enter a string.
abc   <-- 入力した文字列。最後に Enterキーを押している
abc

この方法は、// による方法よりも記述量が多くなるので、多少面倒です。そのため、C++ プログラマーのほとんどは // を好んで使います。ただし、/* と */ による方法にも利点があります。代表的な２つの利点を紹介します。

#include <iostream>

int main()
{
    constexpr auto member_num = 10;   // 会員の人数
    constexpr auto absent_num = 1;    // 欠席者の人数
    constexpr auto entry_fee = 1000;  // 参加費

    // 徴収した参加費の合計を出力
    std::cout << (member_num /*- absent_num*/) * entry_fee << "\n";
}

10000

/*
    徴収した参加費の合計を出力するプログラム。

    登録がある会員の人数と、当日の欠席者の人数、および１人当たりの参加費のデータを使って、
    実際に徴収することができた参加費の合計額を求めている。
*/
#include <iostream>

int main()
{
    constexpr auto member_num = 10;   // 会員の人数
    constexpr auto absent_num = 1;    // 欠席者の人数
    constexpr auto entry_fee = 1000;  // 参加費

    // 徴収した参加費の合計を出力
    std::cout << (member_num - absent_num) * entry_fee << "\n";
}

9000

#include <iostream>

int main()
{                                       /*
    constexpr auto member_num = 10;     会員の人数
    constexpr auto absent_num = 1;      欠席者の人数
    constexpr auto entry_fee = 1000;    参加費
                                        */

    // 徴収した参加費の合計を出力
    std::cout << (member_num - absent_num) * entry_fee << "\n";
}

#include <iostream>

int main()
{
    constexpr auto member_num = 10;   // 会員の人数
    constexpr auto absent_num = 1;    // 欠席者の人数
    constexpr auto entry_fee = 1000;  // 参加費

/*
    /* 徴収した参加費の合計を出力 */
    std::cout << (member_num - absent_num) * entry_fee << "\n";
*/
}

文字列リテラル内のコメント記号

文字列リテラルの中に // や /*、*/ が現れる場合、それはコメントをあらわす記号としては扱われません。文字列を構成する文字の並びであると認識されます。

#include <iostream>

int main()
{
    std::cout << "Hello, // World\n";
    std::cout << "Hello/*, World*/\n";
}

実行結果：

Hello, // World
Hello/*, World*/

コメントに書くこと・書かないこと

コメントには、後からソースコードを読む人（自分かもしれない）が、意味や意図を理解する助けになることを書くようにします。

目指すべきところは、「分かりやすくコメントを書くこと」ではなく、「コメントを書かなくても理解しやすいソースコードを書く」ことです。たとえば、変数につける名前を工夫したり、リテラルに名前を与えたりすることは、コメントに頼らずにソースコードを理解しやすくする有効な方法です。

ソースコードをみればすぐに分かることにまで、いちいちコメントを書く必要はありません。たとえば、次のプログラムのコメントは不要なものです。

#include <iostream>

int main()
{
    int x {10};  // 変数 x を宣言している。初期値は 10

    std::cout << x << "\n";  // 変数 x の値を出力している
}

この手のコメントが学習のときに役に立つことはあります。学習のときには、はじめて使った機能や文法がどういう意味であったかをメモしておきたい場合もあるでしょうから、このようなコメントを完全否定はしませんが、本格的な開発にまで持ち込まないほうがいいです。

コメントを書きすぎることには、次のようなデメリットがあります。

1. 書き手は、ソースコードとコメントの整合性をずっと維持しなければならない
2. 読み手は、ソースコードとコメントの両方を読む必要があり、労力が増す

１は、ソースコードを書いたときに同時に書き添えたコメントがあるとして、あとでソースコードを修正するときに、コメントが嘘にならないようにしなければならないという話です。厄介なことに、修正したソースコードから離れた場所に書いたコメントが影響を受ける可能性もありますから、コメントを書きすぎないことにも意味があります。

たとえば、変数を宣言する行に「この変数 x は、この後の計算式で使う」とコメントを書きました。その計算式はたしかに存在しましたが、あとになって不要になったので消すことになったとします。計算式があった行と、変数を宣言している行は離れていますが、このコメントを忘れずに修正できるでしょうか？

２は、ソースコードを理解する側の負担の問題です。特に、１が怠られていたときには更なる巨大な負担を与えます。つまり、ソースコードとコメントを見比べたときに、矛盾を見つけてしまったら、読み手はその違いの理由をなんとか理解しなければならなくなるということです。コメントは実行結果に影響しないのだから、ソースコードを信じるべきなのかもしれませんが、コメントに書かれている動作を目指してつくっていたはずが、ソースコードをそのように実装できていないのかもしれません。

ソースコードの読み手は、日本語で書かれたコメントがあると、ソースコードよりもコメントを優先して読み、コメントの記述を信じ込んでしまうこともあります。

書くといいコメントの例を挙げておきます。

1. ソースファイルの概要を解説するコメントを、ソースファイルの先頭に書く
2. 必要に応じて、ソースファイルの作者や連絡先の情報を、ソースファイルの先頭に書く
3. 必要に応じて、ライセンス・利用規約に関する表記を、ソースファイルの先頭に書く
4. ある程度の大きさをもった処理の集まりについて、その概要をその集まりの冒頭に書く
5. 高度な専門知識や、あまり知られていない手法を使っている処理について、その参考になる書籍、URL、論文などを示す
6. 作りかけになっているところや、改善が必要なところ、特定の環境（OS やコンパイラの種類・バージョンなど）に依存しているところを示す
7. 単純に分かりづらいと感じるところを補足する
   • ただし、まずはソースコードを分かりやすくする工夫を凝らすべき

まとめ

• プログラムの内容の説明をコメントとして記述できる
• コメントには、// による１行コメントと、/* と */ で範囲を指定するコメントがある
• /* と */ によるコメントは入れ子にできない
• 文字列リテラルの中にあらわれる //、/*、*/ はコメントの意味にはならず、ただの文字である
• コメントは、ソースコードだけでは分かりやすく表現できないところを補足するために用いる。コメントを分かりやすく書くのではなく、ソースコードを分かりやすく書くことを目指すべき
• コメントには、一時的にソースコードの一部を無効化して（コメントアウト）、実行結果の変化を確認する使い道もある

新C++編の【本編】の各ページには、末尾に練習問題があります。ページ内で学んだ知識を確認する簡単な問題から、これまでに学んだ知識を組み合わせなければならない問題、あるいは更なる自力での調査や模索が必要になるような高難易度な問題をいくつか掲載しています。