clean-code

クリーンコードスキル

このスキルは、Robert C. Martin（Uncle Bob）による「Clean Code」の原則を体現しています。「動くコード」を「クリーンなコード」に変えるために使用してください。

🧠 中核となる考え方

「元の作者以外の開発者にも読みやすく、改善できるコードはクリーンです。」— Grady Booch

使用する場面

次のような場合に、このスキルを使用してください。

• 新しいコードを書く場合：最初から高品質を確保するため。
• プルリクエストをレビューする場合：建設的で、原則に基づいたフィードバックを行うため。
• レガシーコードをリファクタリングする場合：コードの不吉な臭いを見つけて取り除くため。
• チームの基準を改善する場合：業界標準のベストプラクティスに沿うため。

これらは設計上のヒューリスティックであり、普遍的な言語規則でも、動作を変更する権限でもありません。実際のリポジトリの規約に従ってください。例外と結果型、null 許容性、引数の数、テストの頻度は、言語やタスクによって異なります。必要な根拠、セキュリティ、ライセンスに関するコメントは維持してください。リファクタリングは対象範囲内にとどめ、関連する動作を検証してください。

1. 意味のある名前

• 意図が伝わる名前を使う：d ではなく elapsedTimeInDays を使います。
• 誤解を招く名前を避ける：実際には Map であるものに accountList を使わないでください。
• 意味のある違いを表す：ProductData と ProductInfo のような名前は避けてください。
• 発音しやすく、検索しやすい名前を使う：genymdhms のような名前は避けてください。
• クラス名：名詞を使います（Customer、WikiPage）。Manager や Data は避けてください。
• メソッド名：動詞を使います（postPayment、deletePage）。

2. 関数

• 小さく！：関数は、思っているより短くするべきです。
• 一つのことを行う：関数は一つのことだけを、適切に行うべきです。
• 抽象化のレベルを一つにする：高水準のビジネスロジックと、正規表現のような低水準の詳細を混在させないでください。
• 説明的な名前：check より isPasswordValid のほうが適切です。
• 引数：引数は0個が理想で、1～2個なら問題ありません。3個以上の場合は、非常に強い根拠が必要です。
• 副作用を避ける：関数がひそかにグローバル状態を変更してはいけません。

3. コメント

• 悪いコードにコメントを付けず、書き直す：コメントの多くは、コードで意図を表現できていないことを示しています。
• コードで説明する：

  # Check if employee is eligible for full benefits
  if employee.flags & HOURLY and employee.age > 65:
  

  と

  if employee.isEligibleForFullBenefits():
  

• 良いコメント：法的事項、情報提供（正規表現の意図など）、補足説明（外部ライブラリなど）、TODO。
• 悪いコメント：曖昧なもの、冗長なもの、誤解を招くもの、義務的なもの、雑音になるもの、位置を示すだけのもの。

4. 書式

• 新聞の比喩：高水準の概念を先に、詳細を後に記述します。
• 縦方向の密度：関連する行は近くに配置します。
• 距離：変数は使用箇所の近くで宣言します。
• インデント：構造を読みやすくするために不可欠です。

5. オブジェクトとデータ構造

• データの抽象化：インターフェースの背後に実装を隠します。
• デメテルの法則：モジュールは、操作するオブジェクトの内部を知るべきではありません。a.getB().getC().doSomething() のようなコードは避けてください。
• データ転送オブジェクト（DTO）：公開変数を持ち、関数を持たないクラスです。

6. エラー処理

• 戻り値コードではなく例外を使う：ロジックがすっきりします。
• 最初に try-catch-finally を書く：操作の範囲が明確になります。
• null を返さない：呼び出し側が毎回 null を確認する必要が生じます。
• null を渡さない：NullPointerException の原因になります。

7. 単体テスト

• TDD の三つの法則：
  1. 失敗する単体テストを書くまで、本番コードを書かない。
  2. 失敗させるのに必要な範囲を超えて、単体テストを書かない。
  3. 失敗するテストを通すのに必要な範囲を超えて、本番コードを書かない。
• F.I.R.S.T. の原則：高速（Fast）、独立（Independent）、繰り返し可能（Repeatable）、自己検証可能（Self-Validating）、適時（Timely）。

8. クラス

• 小さく！：クラスは単一責任（SRP）を持つべきです。
• 段階的に読み進めるルール：コードは上から下へ物語を読むように読めることが望ましいです。

9. コードの臭いとヒューリスティック

• 硬直性：変更が難しい。
• 脆弱性：さまざまな箇所で壊れる。
• 移動困難性：再利用が難しい。
• 粘着性：適切な方法で実行するのが難しい。
• 不要な複雑さ／繰り返し。

🛠️ 実装チェックリスト

• この関数は20行未満ですか？
• この関数は1つのことだけを行っていますか？
• すべての名前は検索可能で、意図が明確ですか？
• コードをわかりやすくすることで、コメントを避けられていますか？
• 引数を渡しすぎていませんか？
• この変更に対する失敗するテストはありますか？

例

ユーザーのリクエスト：

名前をわかりやすくし、単位を小さくして、エラーを明示し、動作を維持したまま、この動作するコードをリファクタリングしてください。対象を絞ったテストで検証してください。

制限事項

• タスクが上記の説明の範囲に明確に当てはまる場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。