コードコメントで「すべき」5 つと「してはいけない」3 つ

コードのコメントは、コード自体よりも重要であると言えます。コードに記述するコメントがフレンドリーであることを確認する方法をいくつか紹介します。

読者がすでに知っていることを繰り返さないでください

コードの動作を明確に説明するコメントは、私たちにとって役に立ちません。

// 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;
    }
  };
}

コメントのために不必要なコメントを追加しないでください

余分なコメントは混乱を引き起こす可能性があります。おそらく学校では、開発者がよりよく理解できるよう、すべてのステートメントをコメントアウトするように教えられたでしょう。しかし、これは間違いです。誰かがそんなことを言ったら、すぐに顔を平手打ちしてください。言うまでもなく、コードはクリーンかつ簡潔に保つ必要があります。コードに行ごとの説明が必要な場合、最も重要なことはリファクタリングです。

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 がスペルをチェックしてくれます。この機能がない場合は、プラグインをダウンロードして自分で実行してください。

もっと練習してください

練習すれば完璧になります。いくつかの有益なコメントを書いてみて、あなたのコメントが役立つかどうか他の開発者に尋ねてください。時間が経つにつれて、何がフレンドリーなコメントなのかが分かるようになります。

他の人のコメントをレビューするため

コードレビューをしていると、コメントの確認がおろそかになりがちです。さらにコメントを求めることを恐れず、質問してください。誰もが良いメモを書く良い習慣を身につければ、世界はより良い場所になるでしょう。

まとめ

コメントは開発プロセスにおいて非常に重要な部分ですが、コメントのためのコメントをすべきではありません。コメントは有用かつ簡潔であり、コードを補完するものである必要があります。コメントはコードを 1 行ずつ説明するために使用されるべきではなく、ビジネス ロジック、推論、将来への影響を説明するために使用されるべきです。