clean-code

クリーンコード

このスキルが有効な間に作成、変更、またはレビューするすべてのコードには、以下のエンジニアリング基準が必須です。これらは言語に依存しません。プロジェクトで使用されている言語のイディオムを尊重しながら適用してください。

速度とクリーンさが両立しない場合は、運用上の緊急事態が実証されていない限り、クリーンな解決策を選んでください。近道が避けられない場合は、その影響範囲を限定して明確にし、後から安全に整理できる状態にしてください。

詳しい根拠、例、設計のヒューリスティックについては、reference.mdを参照してください。ルールの解釈が必要な場合や、明白でない設計上の判断に直面した場合に確認してください。

基本ルール

1. コードをよりクリーンな状態にする

変更によって、明瞭さ、命名、簡潔さ、凝集度、テスト容易性、エラー処理、重複の削減、関心事の分離のうち、少なくとも1つを改善してください。単に動くだけのコードを追加してはいけません。理解しやすいコードを追加してください。

2. 読み手を優先する

• 印象的に見せるためではなく、次に担当するエンジニアのためにコードを書いてください。
• ひねったコードより、わかりやすいコードを優先してください。
• 制御フローを明確にしてください。
• 説明しにくいコードは、設計上の問題として扱ってください。

3. 意図が伝わる名前を使う

• 名前から意図がわかるようにしてください。ドメインの用語を一貫して使ってください。
• 汎用的な名前より具体的な名前を優先してください。ドメイン上または外部プロトコル上で本当に適切な場合を除き、data、info、thing、stuff、manager、helper、util、misc、handle、temp、objは避けてください。
• ブール値の名前は述語として読めるようにし（active?、isActive、hasItems、retryable?など）、言語の慣習に従ってください。
• コレクションには複数形の名前を使ってください。
• 関数名には、曖昧な動作ではなく実行する処理を表す名前を使ってください（do_invoiceではなくcalculate_invoice_total）。

4. メソッドを小さく、目的を絞ったものにする

• メソッドは、1つの抽象化レベルで1つのことだけを行うようにしてください。
• 1つのメソッドにビジネスルール、フォーマット、永続化、外部呼び出し、エラー復旧を混在させないでください。メソッドに複数の段階が生じたら、ヘルパーに切り出してください。
• パラメーターは0個、1個、または2個を優先してください。3個の場合は慎重に検討し、それ以上なら、値オブジェクトまたはドメインオブジェクトが不足している可能性があります。
• 別々のメソッドのほうが意図を明確に表せる場合、動作を切り替えるためにブール値のパラメーターを使わないでください。

5. 抽象化レベルを分離する

• 1つのメソッドに高レベルのポリシーと低レベルの仕組みを混在させないでください。
• オーケストレーションと実装の詳細、ドメインロジックとI/O、フレームワークとの接着部分、シリアライズを分離してください。

6. 副作用を明示する

• 問いに答えることとアクションの実行を両方行うメソッドは避けてください。
• 副作用は、名前と配置からわかるようにしてください。隠れた変更は避けてください。
• 暗黙的なグローバルより、明示的な依存関係を優先してください。

7. 条件分岐を制御する

• 深いネストよりガード節を優先し、分岐を浅くしてください。
• 複雑な条件式は、意図が伝わる名前に切り出してください。
• 複数の箇所で条件ロジックを繰り返さないでください。
• より明確に読める場合は、肯定形の条件を優先してください。

8. エラーを設計の一部として扱う

• 前提が無効な場合は速やかに失敗させ、エラーを黙って握りつぶさないでください。
• 役に立つ診断情報を添えて、エラーを送出するか返してください。
• 正常系の処理は読みやすく保ってください。
• 正当な理由なく、検証エラー、ドメインエラー、インフラストラクチャ障害を曖昧にまとめないでください。

9. モジュールとクラスの凝集度を保つ

• 各単位が変更される理由を明確に1つにしてください。公開する範囲は小さく保ってください。
• 神オブジェクト、神モジュール、何でも詰め込むユーティリティ名前空間は避けてください。
• 絡み合った継承よりコンポジションを優先してください。

10. 適切なレベルで重複を取り除く

• 重複したロジック、判断、ビジネスルール、意味のあるリテラルを取り除いてください。
• 表面的に似た行をまとめるためだけに、時期尚早で不安定な抽象化を作らないでください。意味の適切なレベルで重複を排除してください。

11. テストファーストで作業する

• テスト駆動開発を基本とします。動作を変更する場合、バグを修正する場合、または機能を追加する場合は、まず失敗するテストを作成または更新します。
• 付随的な実装の詳細ではなく、動作をテストします。
• テストは読みやすく、決定的で、実行順序に依存せず、期待される結果に基づいて命名されている必要があります。セットアップは小さく、意図が明確になるようにします。
• 実行可能な場合は、バグを修正する前に回帰テストを追加します。
• 厳密なテストファーストが本当に難しい場合（テストハーネスがない、レガシーな制約があるなど）は、その旨を明記し、すぐに最も有用なテストを追加して、対象領域を以前よりテストしやすくします。

12. 作業しながらリファクタリングする

• 変更する箇所では、わかりにくい名前を改善し、長いメソッドを分割し、不要なコードを削除します。
• リファクタリング中もテストが通る状態を維持します。
• 全体の整理が対象範囲外の場合は、近くにある意味のある境界を改善し、明確なメモを残します。

13. 言語の慣用表現を尊重する — 意図を曖昧にせずに

• 対象言語に堪能なエンジニアにとって明快な場合に限り、その言語の慣用表現を使用します。
• 共有された可変状態を持つ手続き型スクリプトより、小さく表現力のある単位を優先します。
• 呼び出し側と定義側の両方で通常のコードのほうが明快な場合は、メタプログラミング、マジック、DSL を避けます。
• データベース、API、キュー、フレームワークなどの外部システムは明確な境界の背後に隔離し、ベンダー固有の知識が各所に漏れないようにします。

14. 完了の定義

次の条件を満たした場合にのみ、タスクは完了です。

• 実装が正しい
• 設計が理解しやすく、名前が明確である
• 変更したコードが以前より整理されている
• 関連するテストが存在し、合格している（実際の制約を明記した場合を除き、テストファーストである）
• 変更箇所に明らかな重複や不要なコードが残っていない