mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-05-09 22:07:32 +02:00
JiangCheng
1d1df9235b
- Translate all 101 markdown files: P1 core, all 10 modules, examples, auxiliary docs (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CLAUDE.md, etc.), peripheral docs (.github/, docs/, resources/, scripts/) - Translate comments and user-facing messages in 06-hooks/*.sh examples - Copy 05-mcp/*.json examples (standard JSON, no comments) - Update root README.md language switcher to include 日本語 - Add ja/TRANSLATION_NOTES.md (glossary + style guide) All translations pass pre-commit quality gates (markdown-lint, cross-references, mermaid-syntax, link-check, build-epub).
116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
<!-- 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
|