Clean Code Practices

概要

このスキルは、ロバート・C・マーティン（Uncle Bob）が『Clean Code』で体系化した コード品質のプラクティスを提供します。可読性が高く、保守しやすいコードを書くための 基本原則と具体的なテクニックを解説します。

核心原則:

• コードは書かれるより読まれる回数が圧倒的に多い
• 明確さが簡潔さに勝る
• 小さなものは理解しやすい

対象ユーザー:

• ビジネスロジック実装エージェント（.claude/agents/logic-dev.md）
• コードレビュー担当者
• 品質向上を目指す開発者

リソース構造

clean-code-practices/
├── SKILL.md                              # 本ファイル
├── resources/
│   ├── meaningful-names.md               # 意味のある命名の詳細
│   ├── small-functions.md                # 小さな関数の原則
│   ├── dry-principle.md                  # DRY原則の適用
│   └── comments-and-documentation.md     # コメントの書き方
├── scripts/
│   └── measure-code-quality.mjs          # コード品質測定
└── templates/
    └── code-review-checklist.md          # コードレビューチェックリスト

コマンドリファレンス

リソース読み取り

# 意味のある命名
cat .claude/skills/clean-code-practices/resources/meaningful-names.md

# 小さな関数の原則
cat .claude/skills/clean-code-practices/resources/small-functions.md

# DRY原則
cat .claude/skills/clean-code-practices/resources/dry-principle.md

# コメントの書き方
cat .claude/skills/clean-code-practices/resources/comments-and-documentation.md

スクリプト実行

# コード品質測定
node .claude/skills/clean-code-practices/scripts/measure-code-quality.mjs src/features/

意味のある命名（概要）

意図を明確にする

変数名、関数名、クラス名は、その存在理由、機能、使用方法を表現すべきです。

基準:

• 名前だけで何をするか分かるか？
• コメントなしで理解できるか？
• 発音しやすいか？

命名規則

• 変数: 内容を表す名詞（例: userCount, orderItems）
• 関数: 動詞で始まる（例: calculateTotal, validateEmail）
• クラス: 名詞（例: UserService, OrderProcessor）
• ブール値: is/has/canで始まる（例: isValid, hasPermission）

詳細: resources/meaningful-names.md

小さな関数（概要）

単一責任

関数は一つのことだけを行い、それを上手くやるべきです。

基準:

• 関数が一つのことだけをしているか？
• 関数名が処理内容を正確に表しているか？
• 抽象度が統一されているか？

サイズの目安

• 理想: 5-10行
• 上限: 20-30行
• ネスト: 2段階まで

詳細: resources/small-functions.md

DRY原則（概要）

重複の排除

"Don't Repeat Yourself" - 同じ知識を複数箇所に持たない。

適用条件:

• 同じロジックが3回以上繰り返される
• 変更時に複数箇所を修正する必要がある
• コピー&ペーストでコードを書いている

注意点

• 早すぎる抽象化を避ける
• 偶然の類似と本質的な重複を区別する

詳細: resources/dry-principle.md

コメント（概要）

自己文書化コード

コメントよりも、コード自体で意図を表現することを優先します。

良いコメント:

• 法的情報
• 意図の説明（なぜそうしたか）
• 警告
• TODO（一時的）

悪いコメント:

• 冗長な説明
• 誤解を招くコメント
• コメントアウトされたコード
• 変更履歴

詳細: resources/comments-and-documentation.md

ワークフロー

コード品質改善

1. コードを読む
   ↓
2. 問題点を特定
   - 命名は明確か？
   - 関数は小さいか？
   - 重複はないか？
   ↓
3. 優先順位を決定
   - 可読性への影響
   - 修正の容易さ
   ↓
4. 一つずつ改善
   ↓
5. テストで確認

コードレビュー

1. 全体構造の確認
   ↓
2. 命名のチェック
   ↓
3. 関数サイズのチェック
   ↓
4. 重複のチェック
   ↓
5. フィードバック作成

ベストプラクティス

すべきこと

1. 読みやすさを優先:

   • 明確さが簡潔さに勝つ
   • 理解しやすいコードを書く

2. 継続的に改善:

   • ボーイスカウトルール：来た時よりも綺麗に
   • 小さな改善を積み重ねる

3. 一貫性を保つ:

   • プロジェクト内で命名規則を統一
   • 既存のスタイルに従う

避けるべきこと

1. 不明瞭な命名:

   • ❌ d, temp, data, info
   • ✅ elapsedTimeInDays, tempUserId, userData

2. 巨大な関数:

   • ❌ 100行の関数
   • ✅ 10-20行の小さな関数

3. コードのコピー&ペースト:

   • ❌ 同じロジックを複数箇所に
   • ✅ 共通関数に抽出

関連スキル

• .claude/skills/refactoring-techniques/SKILL.md (.claude/skills/refactoring-techniques/SKILL.md): コード改善のテクニック
• .claude/skills/tdd-red-green-refactor/SKILL.md (.claude/skills/tdd-red-green-refactor/SKILL.md): テストを伴う改善
• .claude/skills/solid-principles/SKILL.md (.claude/skills/solid-principles/SKILL.md): 設計原則

メトリクス

関数サイズ

目標: 20行以下

循環的複雑度

目標: 10以下

認知的複雑度

目標: 15以下

参考文献

• 『Clean Code』 ロバート・C・マーティン著

  • 第2章: 意味のある名前
  • 第3章: 関数
  • 第4章: コメント

• 『リーダブルコード』 Dustin Boswell、Trevor Foucher著

変更履歴