<!-- i18n-source: clean-code-rules.md -->
<!-- i18n-source-sha: 7f2e773 -->
<!-- i18n-date: 2026-04-27 -->

# AI コード生成のためのクリーンコードルール

これらのルールは、保守可能でプロ品質のコードを生成するためのコード生成指針である。

## 意味のある名前
- 何のために存在するかを示す、意図を明らかにする名前を使う
- 誤解を招く表現や、意味のない区別（例：`data`、`info`、`manager`）を避ける
- 発音可能で検索可能な名前を使う
- クラス名：名詞（例：`UserAccount`、`PaymentProcessor`）
- メソッド名：動詞（例：`calculateTotal`、`sendEmail`）
- 心理的マッピングやエンコーディング（ハンガリアン記法、プレフィックス）を避ける

## 関数
- 関数は小さく保つ（理想は 20 行未満）
- 1 つのことだけを行う — 単一責任原則
- 1 関数につき 1 段階の抽象度
- 引数を制限する：理想は 0〜2 個、最大 3 個、フラグ引数は避ける
- 副作用を作らない — 関数は名前どおりのことだけをする
- コマンド（状態を変える）とクエリ（情報を返す）を分離する
- エラーコードよりも例外を使う

## コメント
- コードは自己説明的であるべき — できる限りコメントは避ける
- よいコメント：法的情報、警告、TODO、公開 API のドキュメント
- 悪いコメント：冗長、誤解を招く、または悪いコードの言い訳
- コードをコメントアウトしない — 削除する（履歴はバージョン管理が保持する）
- コメントが必要だと感じたら、代わりにコードのリファクタリングを検討する

## フォーマット
- ファイルは小さく、焦点を絞って保つ
- 縦のフォーマット：関連する概念は近くに、空行で概念を区切る
- 横のフォーマット：行長を制限する（80〜120 文字）
- 一貫したインデントとチームスタイルを使う
- 関連する関数を近くにまとめる

## オブジェクトとデータ構造
- オブジェクト：データを抽象化の背後に隠し、メソッド経由で振る舞いを公開する
- データ構造：データを公開し、振る舞いは最小限に抑える
- デメテルの法則：直接の友人にしか話しかけない（`a.getB().getC().doSomething()` を避ける）
- ゲッター／セッターによって内部構造を盲目的に公開しない

## エラー処理
- リターンコードやエラーフラグではなく、例外を使う
- 失敗の可能性があるコードは `try-catch-finally` を先に書く
- 例外メッセージにはコンテキストを含める
- `null` を返さない — 空のコレクションを返すか、Optional/Maybe を使う
- `null` を引数として渡さない

## クラス
- 小さなクラス：行数ではなく責任の数で測る
- 単一責任原則：変更する理由が 1 つだけ
- 高い凝集度：多くのメソッドで使われるクラス変数
- 低い結合度：クラス間の依存関係を最小化する
- 開放／閉鎖原則：拡張に対して開かれ、修正に対して閉じている

## 単体テスト
- Fast、Independent、Repeatable、Self-validating、Timely（F.I.R.S.T.）
- 1 テストにつき 1 アサート（または 1 概念）
- テストコードの品質はプロダクションコードと等しい
- 何をテストしているかが分かる読みやすいテスト名
- Arrange-Act-Assert パターン

## コード品質の原則
- **DRY（Don't Repeat Yourself）：** 重複を作らない
- **YAGNI（You Aren't Gonna Need It）：** 仮想の未来のために作らない
- **KISS（Keep It Simple）：** 不要な複雑さを避ける
- **ボーイスカウトルール：** 自分が見つけたときよりきれいな状態でコードを去る

## 避けるべきコードスメル
- 長い関数やクラス
- 重複コード
- デッドコード（未使用の変数、関数、引数）
- フィーチャーエンビー（他クラスに過度に関心を持つメソッド）
- 不適切な親密さ（クラス同士が互いを知りすぎている）
- 長い引数リスト
- プリミティブ強迫（小さなオブジェクトの代わりにプリミティブを多用する）
- switch/case 文（ポリモーフィズムを検討する）
- 一時フィールド（時々しか使われないクラス変数）

## 並行処理
- 並行コードを他のコードから分離する
- 同期／ロック対象のデータのスコープを制限する
- スレッドセーフなコレクションを使う
- 同期セクションは小さく保つ
- 実行モデルとプリミティブを理解する

## システム設計
- 構築と利用を分離する（依存性注入）
- 複雑なオブジェクト生成にはファクトリやビルダーを使う
- 実装ではなくインターフェースに対してプログラミングする
- 継承よりコンポジションを優先する
- デザインパターンは見せびらかすためでなく、簡潔化に役立つときに適用する

## リファクタリング
- 大きな塊ではなく、継続的にリファクタリングする
- 前後で常にテストが通る状態を維持する
- 小さなステップ：一度に 1 つの変更
- 一般的なリファクタリング：Extract Method、Rename、Move、Inline

## ドキュメント
- 自己説明的なコード ＞ コメント ＞ 外部ドキュメント
- 公開 API には明確なドキュメントが必要
- ドキュメントには例を含める
- ドキュメントはコードに近く保つ（理想はコード内）

---

**コア哲学：** コードは書かれる回数の 10 倍読まれる。賢さではなく、可読性と保守性を最適化する。

---
**Last Updated**: April 9, 2026