コードコメントは、コード自体よりも重要と言えるでしょう。ここでは、コードに書くコメントを親しみやすくするための方法をいくつか紹介します：
読者がすでに知っている内容を繰り返さない
コードが何をするかを明確に説明するコメントは、私たちにとって役に立ちません。
// If the color is red, turn it green
if (color.is_red()) {
color.turn_green();
}
推論と歴史をコメントで説明する
コード内のビジネスロジックが後で更新または変更される可能性がある場合は、コメントを残すべきです。
/* The API currently returns an array of items
even though that will change in an upcoming ticket.
Therefore, be sure to change the loop style here so that
we properly iterate over an object */
var api_result = {items: ["one", "two"]},
items = api_result.items,
num_items = items.length;
for(var x = 0; x < num_items; x++) {
...
}
同じ行のコメントを長く書きすぎない
コメントを読むために水平スクロールバーをドラッグすることほど、開発者を腹立たせるものはありません。実際、ほとんどの開発者はこのようなコメントを無視します。読むのが本当に不便だからです。
function Person(name) {
this.name = name;
this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it
}
長いコメントはロジックの上に置き、短いコメントは後ろに置く
コメントが120文字以内であれば、コードの横に置くことができます。それ以外の場合は、コメントをステートメントの上に直接置くべきです。
if (person.age < 21) {
person.can_drink = false; // 21 drinking age
/* Fees are given to those under 25, but only in
some states. */
person.has_car_rental_fee = function(state) {
if (state === "MI") {
return true;
}
};
}
コメントのために不要なコメントを追加しない
蛇足なコメントは混乱を招きます。学校で、すべてのステートメントにコメントを追加するよう教えられたかもしれません。それは開発者の理解を助けると言われています。しかし、それは間違いです。そう言う人がいたら、すぐに平手打ちを2発食らわせてやりましょう。コードはクリーンで簡潔であるべきです。これは疑いの余地がありません。コードが行ごとの説明を必要とするなら、最も必要なのはリファクタリングです。
if (person.age >= 21) {
person.can_drink = true; // A person can drink at 21
person.can_smoke = true; // A person can smoke at 18
person.can_wed = true; // A person can get married at 18
person.can_see_all_movies = true; // A person can see all movies at 17
//I hate babies and children and all things pure because I comment too much
}
コメントのスペルを正しくする
コードコメントのスペルミスに対して言い訳をしてはいけません。IDEがスペルチェックをしてくれます。その機能がない場合は、プラグインをダウンロードして自分でやりましょう！
たくさん練習する
習うより慣れよ。役に立つコメントを書いてみて、他の開発者に自分のコメントが役に立つかどうか聞いてみましょう。時間が経つにつれて、どういうコメントが親しみやすいのかがだんだん分かってくるでしょう。
他人のコメントをレビューする
コードレビューの際、私たちはコメントを確認することをしばしば怠ってしまいます。もっとコメントを求めることを恐れず、疑問を投げかけるべきです。全員が良いコメントを書く良い習慣を身につければ、世界はもっと良くなるでしょう。
まとめ
コメントは開発プロセスにおいて非常に重要な部分ですが、コメントのためにコメントするべきではありません。コメントは有用で簡潔であり、コードを補完するものであるべきです。コメントはコードを行ごとに説明するために使うべきではなく、ビジネスロジック、推論、そして将来への示唆を説明するために使うべきです。