PHP コードのコメントの詳細

コードのコメントは、コード自体よりも重要であると言えます。初心者の皆さんには、コメントを書く習慣を身につけなければなりません。そうしないと、コメントは他人に害を及ぼすだけで、自分自身の利益にはならないことを警告したいと思います。コードに記述するコメントがフレンドリーであることを確認するためのいくつかの方法を紹介します。要約すると、「5 つの推奨事項と 3 つの禁止事項」です。 1. 読者がすでに知っていることを繰り返さないでください (×
)。 軽い読み物 メソッド名については、コードを見ただけで機能が分かるものであれば、コメントを書く必要はありません

// If the color is red, turn it green
if (color.is_red()) {
  color.turn_green();
}

2. 理由や経緯を説明するためにコメントを書く必要があります。 √) コード内のビジネス ロジックを将来的に更新または変更する必要がある場合は、コメントを残す必要があります:

/* 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++) {
  ...
}

3. 同じ行に非常に長いコメントを書かないでください。 (×) 開発者にとって、水平スクロールバーをドラッグしてコメントを読むことほど興味深いものはありません。実際、ほとんどの開発者は、このようなコメントは読むのに非常に不便であるため、無視することを選択しています。

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
}

4番目に、長いコメントをロジックの上に置き、短いコメントを後ろに置きます(√) コメントが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;
    }
  };
}

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

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
}

6. コメントのスペルは正しくする必要があります(√) コードコメントのスペルミスを言い訳にしないでください。 IDE がスペルをチェックしてくれます。この機能がない場合は、プラグインをダウンロードして自分で実行してください。

7. もっと練習してください
(√)練習すれば完璧になります。役立つコメントをいくつか書いてみて、あなたのコメントが役立つかどうか他の開発者に尋ねてください。時間が経つにつれて、何がフレンドリーなコメントなのかがわかるようになります。
8. 他の人のコメントをレビューする
(√) コードレビュー中、私たちはコメントのチェックを無視することがよくあります。さらにコメントを求めることを恐れず、質問してください。誰もが良いメモを書く良い習慣を身につければ、世界はより良い場所になるでしょう。
9. 注釈について知っておくべきことの重要なまとめ
コメントは開発プロセスの非常に重要な部分ですが、コメントのためにコメントするべきではありません。コメントは有用かつ簡潔であり、コードを補完するものである必要があります。コメントはコードを 1 行ずつ説明するために使用されるべきではなく、ビジネス ロジック、推論、将来への影響を説明するために使用されるべきです。