C++/Guidelines/余計なコメントを付けない - lab.comp@wiki

コメントを付けることは、よいことである。
しかし、適切でないコメントは、有害でしかない。

例えば、次のようなコードがあったとする。

// 配列aの0～nに0を代入
for (int i = 1; i <= N; ++i) {
    a[i] = 0;  // 配列aのi番目の要素に0を代入
}

上記のようなコメントは、何をしたいのか一目で分からないばかりでなく、内容が間違っている。

コメントは厄介なものである。
コンパイラは命令文の文法的な誤りは指摘してくれても、コメントの誤りに関しては何ら教えてはくれない。
コードを修正する場合は、必ず、コメントも修正するように意識すべきだ。

また、「処理の説明」をしているコメントは、命令文との重複であり、ソースコードの無駄づかいにすぎない。
ソースコードの行数が増えるほど、反比例して理解しやすさが損なわれることを忘れてはならない。
コメントは、「処理の説明」ではなく「何をやりたいか」を簡潔に書くべきであって、無駄なコメントは害にしかならない。

例えば、例に挙げたコードは次のように直すことができる。

例1)
for (int i = 1; i <= N; ++i) a[i] = 0;    // 配列aを初期化

例2)
std::fill(a, a + N, 0);    // 配列aを初期化

さらに言うなら、意味があり、覚えやすい名前をプログラムで使用していれば、コメントを追加する必要はほとんどない。
例えば、次のようなコードを見てみよう。

double a = 10.0;                  // 基数
double b = 2.0;                   // 指数
double ret = std::pow(a, b);      // a^bを計算する
std::cout << ret << std::endl;    // a^bを表示

悪しき変数名の付け方の典型例である。
aとbは何の値が格納されているかもわからず、retは何の結果を格納しているのか想像することもできない。
このような場合は、次のようにすると途端にわかりやすくなる。

double number_base = 10.0, exponent = 2.0;
double powered_value = std::pow(number_base, exponent);
std::cout << powered_value << std::endl;

このようにわかりやすい名前を付けると、コメントをつける必要がない場合が多い。

---

---