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

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

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

---

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

1. 明らかなコード:

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

例:

// Increment the counter by 1
counter++;

// Check if the user is an admin
if (user.isAdmin()) {
    // ...
}

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

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

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

// Initialize user object
let user = new AdminUser(); // Actually, it's creating an AdminUser, not a regular user

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

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

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

// Old code
// let data = fetchDataFromAPI();

// New code
let data = fetchDataFromDatabase();

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

---

---

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

1. 意図の明確化:

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

// Using a workaround for browser-specific bug in IE11
if (isIE11()) {
    fixIEBug();
}

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

2. 法的情報:

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

/*
 * Copyright (c) 2024 MyCompany. All rights reserved.
 * Licensed under the MIT License.
 */

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

3. 決定の説明:

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

// Using a binary search because the list is sorted
let index = binarySearch(sortedArray, target);

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

4. パブリック API:

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

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateArea(width, height) {
    return width * height;
}

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

---

---

?役立つコメントを書く

• 明確かつ簡潔であること: コメントは率直かつ要点を絞ったものでなければなりません。コード自体から簡単に理解できるような長ったらしい説明は書かないでください。

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

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

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

// We need to sort the array before performing the search
array.sort();

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

---

---

結論✅

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

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

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

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

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

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