「C++/Guidelines/余計なコメントを付けない」の編集履歴（バックアップ）一覧はこちら
追加された行は緑色になります。
削除された行は赤色になります。
コメントを付けることは、よいことである。
しかし、適切でないコメントは、有害でしかない。
例えば、次のようなコードがあったとする。
// 配列aの0～nに0を代入
for (int i = 1; i <= N; ++i) {
a[i] = 0; // 配列aのi番目の要素に0を代入
}
上記のようなコメントは、何をしたいのか一目で分からないばかりでなく、内容が間違っている。
コメントは厄介なものである。
コンパイラは命令文の文法的な誤りは指摘してくれても、コメントの誤りに関しては何ら教えてはくれない。
コードを修正する場合は、必ず、コメントも修正するように意識すべきだ。
また、「処理の説明」をしているコメントは、命令文との重複であり、ソースコードの無駄づかいにすぎない。
ソースコードの行数が増えるほど、反比例して理解しやすさが損なわれることを忘れてはならない。
コメントは、「処理の説明」ではなく「何をやりたいか」を簡潔に書くべきであって、無駄なコメントは害にしかならない。
例えば、例に挙げたコードは次のように直すことができる。
for (int i = 1; i <= N; ++i) a[i] = 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;
このようにわかりやすい名前を付けると、コメントをつける必要がない場合が多い。
----
#comment(vsize=5)
----
コメントを付けることは、よいことである。
しかし、適切でないコメントは、有害でしかない。
例えば、次のようなコードがあったとする。
// 配列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;
このようにわかりやすい名前を付けると、コメントをつける必要がない場合が多い。
----
#comment(vsize=5)
----
