クリーンなコードを理解する: コメント ⚡️

コードのコメントはソフトウェア開発では必要であると考えられていますが、Clean Code ブックでは、コードはコメントを必要とせずに一目瞭然であるべきだと示唆しています。

コメントをいつ使用するべきか、いつコメントを避けるべきか、JavaScript コードで価値のあるコメントを記述する方法について説明します。

---

?コメントを避けるべき場合

1. 明らかなコード:

コード自体からすでに明らかな場合、コードが何を行っているかを説明するためにコメントを使用しないでください。

例:

リーリー

このような場合、コードは一目瞭然なので、コメントは冗長です。不必要なコメントを追加する代わりに、コードを読みやすくすることに重点を置いてください。

2. 誤解を招くコメント:

コードと一致しないコメントは混乱やエラーを引き起こす可能性があります。コードを更新してもコメントの更新を忘れると、誤解を招きます:

リーリー

ここでのコメントは誤解を招き、後でコードを読む人を混乱させる可能性があります。コメントを削除するか、コードが正確に反映されていることを確認することをお勧めします。

3. コメントアウトされたコード:

古いコードをコメントアウトしたままにすることは、よくある悪い習慣です。コードベースが乱雑になり、混乱する可能性があります:

リーリー

古いコードをコメントアウトしたままにするのではなく、Git などのバージョン管理システムを使用してコードの変更を追跡します。これにより、コードベースがクリーンで集中した状態に保たれます。

---

---

?コメントを使用する場合

1. 意図の明確化:

コードの一部に複雑なロジックがある場合、または回避策が含まれる場合は、コメントによってコードが存在する理由を明確にすることができます:

リーリー

コメントはコードが必要な理由を説明し、将来の開発者に貴重なコンテキストを提供します。

2. 法的情報:

著作権情報やライセンスの詳細を含めるなど、法的理由によりコメントが必要になる場合があります:

リーリー

これらのコメントは必須であり、プロジェクトのライセンスの要求に応じて含める必要があります。

3. 決定の説明:

コード内の特定の決定に正当性が必要な場合は、コメントが役立ちます:

リーリー

このコメントはバイナリ検索が選択された理由を説明し、実装の背後にある理由についての洞察を提供します。

4. パブリック API:

公開 API を作成する場合、特に組み込みのドキュメント ツールがない可能性がある JavaScript では、コメントは API の使用方法を文書化するのに役立ちます。
リーリー

この場合、コメントは関数の使用方法に関する明確なドキュメントを提供しており、それを使用する可能性のある他の開発者にとって特に役立ちます。

---

?役立つコメントを書く

---

• 明確かつ簡潔であること:

  コメントは率直かつ要点を絞ったものである必要があります。コード自体から簡単に理解できるような長ったらしい説明は書かないでください。

• 専門用語を避ける:

  コードを読む人にとって馴染みのない専門用語を避け、理解しやすい言葉を使用します。

• コメントを更新:

  コードが変更された場合は、常にコメントを更新してください。良い経験則は、コードに触れたらコメントを確認することです。

• 「何を」ではなく「なぜ」に焦点を当てます:

  良いコメントは、コードが何をしているのかを説明するのではなく、特定の決定が行われた理由を説明します:
  

  リーリー
このコメントは、検索前に並べ替えが必要な理由を説明し、貴重なコンテキストを追加します。

---

結論✅

---

コメントは役に立つこともありますが、クリーン コードでは、コメントは慎重かつ目的を持って使用する必要があると教えています。

目標は、コメントがほとんど不要になるほど明確なコードを書くことです。

コメントが必要な場合は、意味があり正確であることを確認し、コードを読む人に価値を提供してください。

これらのガイドラインに従うことで、コードの品質が向上するだけでなく、他の人 (そして将来の自分) がコードを理解し、保守しやすくなります。

コーディングを楽しんでください!

以上がクリーンなコードを理解する: コメント ⚡️の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。