コード品質の基礎

高品質コードの4つの目標

目標	問うべき質問	失敗パターン
動作する	問題を正しく解決しているか？	バグ、未処理のエッジケース、要件の未充足
動き続ける	周囲の変化に耐えられるか？	脆弱な依存関係、テストがない、隠れた仮定
適応可能である	要件変更があっても書き直さずにすむか？	堅い結合、過度な設計、ハードコードされた仮定
車輪の再発明をしない	実証済みのソリューションを再利用しているか？	既に解決された問題向けのカスタムコード、重複した作業

コード品質の6つの柱

柱	意味	主要なテクニック
読みやすい	他のエンジニアがすぐに理解できる	記述的な名前付け、クリーンなレイヤー、一貫したスタイル
驚きがない	動作が予期と一致する(POLA)	明示的なコントラクト、マジック値なし、隠れた副作用なし
誤用しにくい	正しくない方法で使う方が難しい	型安全性、イミュータビリティ、検証された構築
モジュール化されている	コンポーネントを独立して入れ替えられる	インターフェース、DI、関心の分離、凝集度
再利用可能で一般化できる	1つのケースだけでなく、広く問題を解決する	焦点を絞ったパラメータ、ジェネリクス、仮定を避ける
テスト可能である	分離して検証できる	モジュール化がテスト可能性を実現；設計時から考慮する

POLA = Principle of Least Astonishment(最小驚き原則)。関数が合理的な呼び出し側が予期しないことをする場合、たとえ「動作」しても、それは設計上のバグです。

現代的な追加事項(2024-2026年 業界コンセンサス)

関心事	現在明示的な理由	元々の分類
セキュア	シフトレフトセキュリティ；設計時の脅威モデル	「動作する」に暗黙的に含まれていた
効率的	リソース最適化は事後的ではなく、設計上の選択	「動作する」に包含されていた
信頼できる	明示的なエラーリカバリーと段階的な機能低下	「動き続ける」に包含されていた

判定表

「これを抽象化すべきか？」

シグナル	アクション
同じロジックが2箇所以上に現れている	共有する関数/クラスに抽出する
関数を1文で説明できない	より小さな関数に分割する
クラスのメソッドグループが異なるフィールドを使用している	別のクラスへの分割を検討する
1つの機能を変更するために多くのファイルに触れる必要がある	モジュール化とレイヤー境界を改善する
ユースケースが1つだけ存在する	待つ — 時期尚早に抽象化しない

「品質努力をどこに投資すべきか？」

状況	焦点	根拠
グリーンフィールドプロジェクト	モジュール化、クリーンなインターフェース	基礎の決定は複合的に影響；早期に構造を整える
レガシーコードベース	テスト、読みやすさ	安全に変更する前に理解する
高トラフィックサービス	信頼性、効率性、テスト	本番障害は高くつく
プロトタイプ/スパイク	動作するコード、速度	アイデアを検証；書き直しを計画する
共有ライブラリ/API	誤用しにくさ、驚きがなさ	コンシューマーがどう使うかを予測できない
セキュリティに関連するコード	セキュリティ、テスト可能性	違反は壊滅的で信頼を失わせる

チェックリスト

コード作成前に

• 問題が明確に理解されている(要件、制約、エッジケース)
• 既存ソリューションをチェックした(ライブラリ、共有コード、先行事例)
• テスト戦略を検討した(これをどのように検証するか？)
• 主要なトレードオフを識別した(何を選択し、何を諦めるか？)

コード品質の自己レビュー

• 関数が1文に翻訳できる
• 驚きがない：動作が名前と型に一致している
• 誤用しにくい：可能な限り無効な状態を表現できない
• モジュール化されている：変更が局所化され、散らばっていない
• テスト可能である：複雑なセットアップなしでユニットテストできる
• クリーンな抽象化：API が実装詳細をリークしていない