クリーンコード フレームワーク

意図を伝え、予期しない挙動を最小化し、変更を歓迎するコードを書くための規律ある手法です。新しいコードを書く際、プルリクエストをレビューする際、レガシーシステムをリファクタリングする際、またはコード品質の改善についてアドバイスする際に、これらの原則を適用します。

コアの原則

コードは書かれるよりもはるかに頻繁に読まれます。読み手のために最適化してください。 命名の選択肢、関数の境界、フォーマット上の決定は、すべて明確さを加えるか、コストを加えるかのいずれかです。コード読取に費やされる時間と、コード作成に費やされる時間の比率は 10:1 をはるかに上回っています。コードを読みやすくすることは、書きやすく、デバッグしやすく、拡張しやすくします。

基礎: クリーンコードは機械的にルールに従うことではなく、職人としての仕事を大事にすることです。クリーンなコードベースは、よく書かれた散文のように読めます。名前は意図を明かし、関数は1ステップずつストーリーを語り、暗い隅に潜んでいる予期しない挙動はありません。ボーイスカウト・ルールが当てはまります。常にコードを見つけた時より良い状態で残してください。

スコアリング

目標: 10/10。 コードをレビューまたは書く際に、以下の原則への準拠に基づいて 0-10 で評価します。10/10 はすべてのガイドラインに完全に適合していることを意味します。低いスコアは対処すべきギャップを示します。常に現在のスコアと 10/10 に達するために必要な具体的な改善点を示してください。

• 9-10: 名前が意図を明かし、関数は小さく焦点が当てられ、エラーハンドリングは一貫し、テストはクリーンで包括的です。
• 7-8: ほぼクリーンですが、若干の命名の曖昧性または数個の長い関数があります。テストは存在しますが、エッジケースに欠ける可能性があります。
• 5-6: 混合品質 -- 良いパターンと不明確な名前、重複したロジック、または一貫しないエラーハンドリングが混在しています。
• 3-4: 著しい可読性の問題 -- 複数のことを行う長い関数、誤解を招く名前、不十分または欠落したテスト。
• 1-2: コードは機能しますが、ほぼ読み取り不可能です -- マジックナンバー、謎めいた略語、構造なし、テストなし。

クリーンコード フレームワーク

明確に通信し、変更に適応するコードを書くための6つの規則:

1. 意味のある名前

コアコンセプト: 名前は意図を明かし、誤った情報を避け、コードが散文のように読めるべきです。名前を説明するためにコメントが必要な場合、その名前は間違っています。

なぜ機能するのか: 名前はドキュメンテーションの最も広範な形式です。よく選ばれた名前は、実装を読む必要をなくします。不十分に選ばれた名前は、すべての読み手に著者の意図をリバースエンジニアリングするよう強います。

主要な洞察:

• 名前は、それが存在する理由、何をするのか、どのように使用されるのかに答えるべきです
• 小さなスコープ内のループカウンター以外の単一文字の変数を避けます
• エンコーディング、プレフィックス、名前内の型情報を避けます(ハンガリアン記法は不要)
• クラス名は名詞または名詞句であるべき。メソッド名は動詞または動詞句であるべき
• 1つの概念で1つの単語を一貫して使用: fetch、retrieve、get を混在させない
• より長いスコープはより長く、より説明的な名前を要求します
• 名前変更を恐れないでください -- IDE は簡単にしてくれます

コード適用:

コンテキスト	パターン	例
変数	意図を明かす名前	elapsedTimeInDays ではなく d や elapsed
ブール値	述語フレーズ	isActive、hasPermission、canEdit
関数	アクションを説明する動詞 + 名詞	calculateMonthlyRevenue() ではなく calc()
クラス	責任を説明する名詞	InvoiceGenerator ではなく InvoiceManager
定数	検索可能な全大文字とコンテキスト	MAX_RETRY_ATTEMPTS = 3 ではなくインライン 3
コレクション	複数形の名詞または説明的なフレーズ	activeUsers ではなく list や data

参照: references/naming-conventions.md

2. 関数

コアコンセプト: 関数は小さく、1つのことをし、それをよく行うべきです。理想的な関数は 4-6 行の長さで、0 から 2 個の引数を取り、抽象化の単一レベルで動作します。

なぜ機能するのか: 小さな関数は、名前を付けやすく、理解しやすく、テストしやすく、再利用しやすいです。関数が 1つのことを行う場合、その名前はそれが行うことを正確に説明でき、本体を読む必要をなくします。長い関数はバグを隠し、テストに抵抗し、時間とともに責任を蓄積します。

主要な洞察:

• 関数は 1つのことをし、それをよくし、それだけをすべき
• ステップダウンルール: コードは上から下へのストーリーのように読み、各関数が抽象化の次のレベルを呼び出すべき
• 理想的な引数の数は 0 (無参数)、次に 1 (単項)、次に 2 (二項)。3 個以上 (多項) は正当な理由が必要
• フラグ引数(ブール値)はコード臭 -- 関数が2つのことをすることを意味します
• コマンド・クエリ分離: 関数は状態を変更するか値を返すか、決して両方を行うべきではありません
• 抽出を続ける: ブロックから名前の付いた関数を抽出できる場合、そうしてください
• 関数は副作用を持つべきではありません -- 隠れた状態の変更はありません

コード適用:

コンテキスト	パターン	例
長い関数	名前の付いたステップに抽出	validateInput(); transformData(); saveRecord();
フラグ引数	2つの関数に分割	renderForPrint() と renderForScreen() ではなく render(isPrint)
深いネスト	内側のブロックを抽出	ネストされた if/for の本体を名前の付いた関数に移動
複数のリターン	ガード句を上部に	エラーケースの早期リターン、単一の成功パス
多くの引数	パラメータオブジェクトを導入	new DateRange(start, end) ではなく report(start, end, format, locale)
副作用	効果を明示的にする	checkPassword() を checkPasswordAndInitSession() に名前変更するか分離

参照: references/functions-and-methods.md

3. コメントとフォーマット

コアコンセプト: コメントは、コード内で自分を表現できないことの失敗です。良いコードは自己説明的です。コメントが必要な場合、それは 何 ではなく なぜ を説明すべきです。フォーマットは、コードをスキャン可能にする視覚的構造を作成します。

なぜ機能するのか: コメントは腐ります。コードは変わりますが、コメントはしばしば変わらず、誤解を招くドキュメンテーションを作成します。それはドキュメンテーションがないよりも悪いです。クリーンなフォーマット -- 一貫したインデント、概念間の垂直スペース、論理的な順序 -- は、開発者がコードをスキャンする方法を可能にします。読者が新聞をスキャンする方法と同じです: 最初に見出し、要求に応じて詳細。

主要な洞察:

• 最良のコメントはコード自体です -- コメントを書く代わりに、よく命名された関数を抽出します
• 法的コメント(著作権ヘッダー)と TODO コメントは受け入れられます
• パブリック API の Javadoc は価値があります; 内部コードの Javadoc はノイズです
• コメントアウトされたコードは削除すべき -- バージョン管理がそれを記憶しています
• ジャーナルコメント(ファイル内の変更ログ)は時代遅れです -- git log を使用します
• 垂直スペース: 空白行で概念を分離
• 垂直密度: 関連するコードは接近して表示されるべき
• 変数は使用場所の近くで宣言されるべき
• インスタンス変数はクラスの上部で宣言されるべき

コード適用:

コンテキスト	パターン	例
「何」の説明	より良い名前に置き換える	// check if eligible を isEligible() に名前変更
「なぜ」の説明	コメントとして保持	// RFC 7231 requires this header for proxies
コメントアウトされたコード	削除する	バージョン管理に記憶させてください
ファイル組織	新聞の比喩	高レベル関数を上部、詳細を下部に
関連するコード	垂直にグループ化	呼び出し元を呼び出し先の同じファイル内に保持
チームフォーマット	ルールに一度同意する	自動フォーマッター(Prettier、Black、gofmt) を使用

参照: references/comments-formatting.md

4. エラーハンドリング

コアコンセプト: エラーハンドリングはビジネスロジックから分離された関心事です。リターンコードではなく例外を使用し、すべての例外にコンテキストを提供し、決して null を返したり渡したりしません。

なぜ機能するのか: リターンコードは呼び出し元にすぐにチェックを強制し、成功パスをエラーチェックロジックで汚します。例外を使用すると、成功パスをエラーハンドリングから分離でき、両方が読みやすくなります。null を返すと、すべての呼び出し元に null チェックを追加するよう強制し、単一の欠けたチェックはソースから遠く離れた NullPointerException を生成します。

主要な洞察:

• try-catch ブロックを最初に書く -- トランザクション境界を定義します
• チェック例外ではなく、チェックなし例外を使用する -- チェック例外は開放・閉鎖の原則に違反します
• 情報的な例外メッセージを作成: 失敗した操作とコンテキストを含める
• 失敗の型ではなく、呼び出し元のニーズに関連して例外クラスを定義
• スペシャルケース パターン: null の代わりにスペシャルケース オブジェクトを返す(例: 空リスト、ゲストユーザー)
• null を返さない -- 空のコレクション、Optional、または throw を返す
• null を渡さない -- null 引数の合理的な動作は存在しません
• サードパーティ API をラップして、それらの例外をドメインに変換します

コード適用:

コンテキスト	パターン	例
Null 戻り	空のコレクションまたは Optional を返す	return Collections.emptyList() ではなく return null
エラーコード	例外に置き換える	throw new InsufficientFundsException(balance, amount)
サードパーティ API	アダプタでラップ	PortfolioService はベンダー API をラップし、例外を変換
Null 引数	アサーションで高速に失敗	Objects.requireNonNull(user, "user must not be null")
スペシャルケース	Null Object パターン	null チェックではなく、デフォルト動作を持つ GuestUser
エラー内のコンテキスト	操作 + 状態を含める	"Failed to save invoice #1234 for customer 'Acme'"

参照: references/error-handling.md

5. ユニットテスト

コアコンセプト: テストはファーストクラスのコードです。本番コードと同じ規律で、クリーン、読み取り可能、維持される必要があります。汚いテストはテストがないことより悪い -- それは、すべての変更を遅くする負債になります。

なぜ機能するのか: クリーンなテストは実行可能なドキュメンテーションとして機能し、システムが意図する動作を正確に示します。それはリファクタリングの安全網と、すべての変更の回帰チェックを提供します。テストがなければ、すべての変更は潜在的なバグです。汚いテストがあれば、すべての変更は読み取り不可能なテストコードとの戦闘を必要とします。

主要な洞察:

• TDD の3つの法則: (1) 最初に失敗するテストを書く、(2) 失敗するのに必要な分だけテストを書く、(3) 合格するのに必要な分だけコードを書く
• テストあたり 1 つの概念 -- 必ずしも 1 つのアサートではなく、1 つの論理的なアサーション
• テストは読み取り可能であるべき: ビルド・操作・チェック パターン(Arrange-Act-Assert) を使用
• F.I.R.S.T. 原則: Fast(速い)、Independent(独立した)、Repeatable(繰り返し可能)、Self-validating(自己検証)、Timely(タイムリー)
• テスト名はシナリオと期待される動作を説明すべき
• テストコードは本番コードと同じリファクタリング注意に値する
• ドメイン固有テスト言語: DSL のように読めるヘルパー関数を作成

コード適用:

コンテキスト	パターン	例
テスト構造	Arrange-Act-Assert	セットアップ、実行、検証 -- 明確に分離
テスト命名	シナリオ + 期待される動作	shouldRejectExpiredToken ではなく test1
共有セットアップ	ビルダー/ファクトリを抽出	aUser().withRole(ADMIN).build()
複数のシナリオ	パラメータ化されたテスト	1つのテスト メソッド、複数の入出力ペア
不安定なテスト	外部依存を削除	時間、ネットワーク、ファイルシステムをモック
テスト可読性	ドメイン固有ヘルパー	assertThatInvoice(inv).isPaidInFull()

参照: references/testing-principles.md

6. コード臭とヒューリスティック

コアコンセプト: コード臭は、より深い設計問題の表面的な指標です。それらをすばやく認識し、的を絞ったリファクタリングを適用することを学びます。すべての臭いが即座のアクションを必要とするわけではありませんが、それらを無視すると技術的負債が蓄積します。

なぜ機能するのか: 臭いはヒューリスティック -- 深い分析を必要とすることなく、可能性のある問題を指します。「この関数の引数が多すぎる」または「このクラスは機能の羨望を持っている」をすばやく特定できる開発者は、漠然とした「クリーンアップ」の取り組みではなく、的を絞った改善を行うことができます。

主要な洞察:

• コメント: 不適切な情報、時代遅れのコメント、コードを繰り返す冗長なコメント
• 関数: 引数が多すぎる、出力引数、フラグ引数、呼び出されることのない死んだ関数
• 一般的な: 明らかな重複、間違った抽象化レベルのコード、機能の羨望(メソッドが自身より別のクラスをより多く使用)、マジックナンバー
• 名前: 間違った抽象化レベルの名前、副作用を説明しない名前、曖昧な短い名前
• テスト: 不十分なテスト、スキップされたテスト、テストされていない境界条件、失敗パス テストなし
• ボーイスカウト・ルールを適用: 見つけた時より、コードをクリーンに残す
• 小さく、テストされたステップでリファクタリング -- 決してリファクタリングと機能追加を同時に行わない

コード適用:

コンテキスト	パターン	例
重複	共有ロジックを抽出	一般的な検証 → validateEmail() ヘルパー
長いパラメータリスト	パラメータオブジェクトを導入	SearchCriteria は関連するパラムをグループ化
機能の羨望	メソッドをデータのクラスに移動	order.calculateTotal() ではなく calculator.total(order)
死んだコード	削除する	未使用の関数、到達不可能なブランチを削除
マジックナンバー	名前の付いた定数	MAX_LOGIN_ATTEMPTS = 5 ではなく裸の 5
散弾銃手術	関連する変更を統合	分散されたロジックを単一モジュールにグループ化

参照: references/code-smells.md

一般的な間違い

間違い	なぜ失敗するのか	修正
名前を縮約する	書くのに数秒を節約し、読むのに数時間を費やす	IDE オートコンプリート; 完全で説明的な名前を使用
「賢い」ワンライナー	書くのは素晴らしい、デバッグは不可能	明確な名前を持つ読み取り可能なステップに展開
コメントの代わりにリファクタリング	コメントは腐る; コードが真実	コメントの代わりに、よく命名された関数を抽出
一般的な例外をキャッチ	予期されたエラーと共にバグを飲み込む	具体的な例外をキャッチ、予期しない例外を伝播させる
エラーパス用テストなし	成功パスは機能し、エッジケースがクラッシュ	すべてのブランチ、境界、失敗モードをテスト
過度な最適化	わずかなパフォーマンスのために意図を曖昧にする	最初にクリーンコードを書く、測定されたボトルネックを最適化
神クラス	1 つのクラス、2000 行、すべてを行う	SRP を適用 -- 責任で分割
テストなしでリファクタリング	回帰をキャッチするための安全網がない	リファクタリング前に特性評価テストを書く
一貫しない規則	すべてのファイルが異なるコードベースのように感じる	スタイルに同意し、リンター とフォーマッターで強制
null をどこにでも返す	Null チェックがウイルスのように広がる	Optional、空のコレクション、または Null Object パターンを使用

クイック診断

すべてのコードベースを監査:

質問	いいえの場合	アクション
本体を読まずに、それぞれの関数を理解できますか?	名前が意図を明かしていない	関数をそれが行うことを説明するように名前変更
すべての関数は 20 行未満ですか?	関数が複数のことをする	副操作を名前の付いたヘルパーに抽出
コメントアウトされたコード ブロックはありませんか?	混乱を作成する死んだコード	それらを削除 -- バージョン管理は履歴を持っています
エラーハンドリングはビジネスロジックから分離されていますか?	Try-catch ブロックが主な流れを汚す	エラーハンドリングを抽出; 例外を返すコードではなく使用
すべてのクラスは単一の責任を持っていますか?	クラスが無関係な責任を蓄積	明確な名前を持つ焦点を当てたクラスに分割
すべてのパブリックメソッドのテストはありますか?	変更の安全網がない	さらなる変更前にテストを追加
テスト名は動作を説明していますか?	テストが失敗すると理解しにくい	shouldDoXWhenY パターンに名前変更
重複は 3 回の発生以下ですか?	コピー ペーストがバグを広げている	共有関数またはモジュールに抽出
マジックナンバーは名前の付いた定数に置き換えられていますか?	意図が生の値の後ろに隠れている	説明的な名前で定数を抽出
すべてのテストを 10 秒以下で実行できますか?	遅いテストはそれらを実行することをためらわせる	外部の deps をモック、統合テストを分割

リファレンスファイル

• naming-conventions.md: 意図を明かす名前、誤った情報を避ける、クラス対メソッド命名、前後の例
• functions-and-methods.md: 小さな関数、引数の数、コマンド・クエリ分離、ステップダウン・ルール、副作用
• comments-formatting.md: 良い対悪いコメント、新聞の比喩、垂直フォーマット、チームルール
• error-handling.md: リターンコード上の例外、null ハンドリング、スペシャルケース パターン、サードパーティ API のラッピング
• testing-principles.md: TDD 法則、F.I.R.S.T. 原則、クリーンテスト パターン、テスト可読性
• code-smells.md: カテゴリ別に整理された包括的な臭いカタログ、的を絞ったリファクタリング付き

さらに学ぶ

このスキルは、Robert C. Martin のソフトウェア職人技についての著作に基づいています:

• 「Clean Code: A Handbook of Agile Software Craftsmanship」 by Robert C. Martin
• 「The Clean Coder: A Code of Conduct for Professional Programmers」 by Robert C. Martin
• 「Clean Architecture: A Craftsman's Guide to Software Structure and Design」 by Robert C. Martin
• 「Refactoring: Improving the Design of Existing Code」 by Martin Fowler

著者について

Robert C. Martin("Uncle Bob") は、1970 年からプログラミングを行っているソフトウェア エンジニア、インストラクター、著者です。彼はアジャイル宣言の共著者であり、Uncle Bob Consulting LLC および Clean Coders の創設者です。彼の本 -- Clean Code (2008)、The Clean Coder (2011)、Clean Architecture (2017)、Clean Agile (2019) -- はコード品質、職業的責任、ソフトウェア設計についての思考方法を、開発者の世代全体に形作りました。Martin は、開発者は自身の仕事の品質に責任を持つ必要がある専門家であり、高速に行く唯一の方法は良く行うことであるという妥協しない立場で知られています。