coding-principles

言語に依存しないコーディング原則

中核となる考え方

1. 速度より保守性：初期開発の速度より、長期的なコードの健全性を優先します
2. まずはシンプルに：要件を満たす最もシンプルな解決策を選びます（YAGNI の原則）
3. 設計の収束：新たな設計上の変更範囲を最小限に抑え、現時点で必要な成果を実現します。永続状態、公開または境界をまたぐ契約、動作モード、再利用可能な抽象化、コンポーネントの分割を選択する場合は、まず設計の収束プロセスを十分に行うだけの変更範囲が生じます
4. 暗黙より明示：コードの構造や命名を通じて意図を明確にします
5. コメントアウトより削除：使われていないコードはコメントアウトせずに削除します

コード品質

継続的な改善

• 受け入れられた成果と適用される境界の範囲内で、変更のリスクや保守コストを軽減できる場合は、関連するコードをリファクタリングします
• コード構造を段階的に改善します
• コードベースを簡潔で焦点の定まった状態に保ちます
• 呼び出し元を確認したうえで、依頼された変更により不要になったことが確認できるコードを削除します。不確かな整理や対象範囲外の整理は、別途報告します

可読性

• 問題領域に即した、意味が明確で説明的な名前を使います
• 名前には完全な単語を使います。略語は、その領域で広く認知されている場合に限り使用できます
• 説明的な名前を使います。1 文字の名前は、ループカウンターや広く知られた規約（i、j、x、y）に限り使用できます
• マジックナンバーや文字列は、名前付き定数にします
• 可能な限り、コード自体から内容がわかるようにします

関数の設計

パラメーターの管理

• 呼び出し側での明確さや、連携した変更への対応が必要な場合は、関連する位置引数をオブジェクト、構造体、または辞書にまとめます。引数の順序が慣例に沿っており、呼び出しが明確な場合や、外部または公開のシグネチャで定められている場合は、位置引数を維持します
• 移行が受け入れられた成果または適用される成果物の一部でない限り、外部または公開のシグネチャを維持します

単一責任

• 各関数は、1 つのことを適切に行うようにします
• 責務を個別に変更できない場合や、制御フローが不明瞭なために現在の単位の理解、検証、再利用が難しくなる場合は、関数を切り出します。切り出しによって人為的な結合が生じる場合は、一貫性のあるドメインフローを維持します
• 複雑なロジックは、適切な名前を付けた別の関数に切り出します
• 関数内の抽象化レベルは 1 つにします

関数の構成

• 可能な限り、副作用のない純粋関数を使います
• データ変換と副作用を分離します
• ネストを減らすために早期リターンを使います
• ネストによって状態遷移や判断の責任が不明瞭になる場合は、早期リターンを使うか処理を切り出します。ネストした構造のほうがドメイン上の判断を明確に表せる場合は、その構造を維持します

エラー処理

エラー管理の原則

• 必ずエラーを処理します：コンテキストを付けてログに記録するか、明示的に伝播させます
• 適切にログを記録します：デバッグに役立つコンテキストを含めます
• 機密データを保護します：パスワード、トークン、個人情報（PII）はログでマスクするか、記録しないようにします
• 早期に失敗させます：エラーをできるだけ早く検出し、報告します

エラーの伝播

• 言語に適したエラー処理の仕組みを使います
• エラーを適切な処理レベルまで伝播させます
• 意味のあるエラーメッセージを提供します
• エラーを再スローする際は、エラーのコンテキストを含めます

依存関係の管理

パラメーター化された依存関係による疎結合

• 外部依存関係はパラメーターとして注入します（クラスではコンストラクターインジェクション、手続き型または関数型コードでは関数パラメーターを使用します）
• 具体的な実装ではなく、抽象に依存します
• モジュール間の依存関係を最小限に抑えます
• モック可能な依存関係を使って、テストを容易にします

参考資料の代表性

採用前の参照確認

既存コードのパターン、API、依存関係を採用する場合：

• IF 参照サンプルが近くにあるファイルのみを対象としている → THEN 採用前に関連するリポジトリ内の使用状況を確認し、そのパターンが代表的であることを確かめます
• IF リポジトリ内に複数のアプローチが共存している → THEN 多数派のパターンを特定し、意図的に選択します。最も近くにあるものを選ぶだけでは不十分です
• IF 外部依存関係（ライブラリ、プラグイン、SDK）を採用する → THEN リポジトリ全体での使用状況と互換性の根拠を確認します。その根拠から必要なバージョンを判断できない場合は、未解決のバージョン選択と、その判断に必要な根拠を記録します
• IF 既存のパターンに従う → THEN 別の選択肢がある場合は、それに従う理由を明記します（例：周辺コードとの一貫性、破壊的変更の回避、調整中の更新）

原則

近くにあるコードは調査の出発点であり、採用の十分な根拠ではありません。モデルとして使用する前に、参照先がリポジトリの規約や現在のベストプラクティスを代表していることを確認してください。

パフォーマンスに関する考慮事項

最適化のアプローチ

• まず測定する：最適化の前にプロファイリングします
• アルゴリズムに注目する：アルゴリズムの計算量をマイクロ最適化より優先します
• 適切なデータ構造を使用する：アクセスパターンに基づいて選択します
• リソース管理：メモリ、接続、ファイルを適切に扱います

最適化するタイミング

• プロファイリングによって実際のボトルネックを特定した後
• パフォーマンスの問題を測定できる場合
• 初期開発中ではなく、測定可能なボトルネックを特定した後にのみ最適化します

コードの整理

構造上の原則

• 関連する機能をまとめる：関連するコードをまとめて配置します
• 関心事を分離する：ドメインロジック、データアクセス、プレゼンテーションを分離します
• 一貫した命名：プロジェクトの規約に従います
• モジュールの凝集度：モジュール内の凝集度を高くし、モジュール間の結合度を低くします

ファイルの整理

• 1つのファイルにつき、主要な責務は1つにします
• 関連する関数／クラスを論理的にまとめます
• アーキテクチャを反映した明確なフォルダー構成にします
• ファイルに独立して変更される責務が含まれている場合、またはナビゲーション、結合、検証のコストが大きくなる場合は分割します。分割によって回避可能な結合やナビゲーションのコストが増える場合は、まとまりのあるファイルを維持します

コメントに関する原則

デフォルト：まずコードで表現する

名前、型、構造が主な表現手段です。コード自体では表現できない情報を伝える場合にのみ、コメントを付ける価値があります。迷った場合はコメントを追加するのではなく、名前を改善します。

コメントごとの判定基準

コメントが正当化されるのは、次のいずれかに答える場合のみです：

• 理由：一見して明らかでない判断の背景にある考え方、トレードオフ、制約
• 制限／エッジケース：読者がコードから推測できない境界条件
• 公開 API の契約：エクスポートされたインターフェースの動作、入力、出力

判断ごとにコメントは1つにします。名前や制御フローですでに示されている内容を言い換えるコメントは削除し、代わりに名前を変更します。

コメントの範囲

• 上記の判定基準に従って、理由、制限、公開契約をコメントします。それ以外（「どのように」行うかを含む）は名前と構造で表現します
• 履歴上の背景はコメントではなく、バージョン管理のコミットメッセージに記録します
• コメントアウトされたコードは削除します（必要な場合は git の履歴から取得します）

コメントの品質

• 日付、バージョン、一時的な状態ではなく、安定した根拠、制限、契約に基づいてコメントを書きます
• コードを変更したらコメントも更新します
• 正しい文法と書式を使用します
• 将来のメンテナーに向けて書きます

リファクタリングのアプローチ

安全なリファクタリング

• 小さなステップ：一度に1つの変更を行います
• 動作する状態を維持する：テストが通る状態を保ちます
• 動作を検証する：変更のたびにテストを実行します
• 段階的な改善：各段階で必要十分な最小限の改善を行います

リファクタリングのきっかけ

• コードの重複（DRY の原則）
• 独立して変化する責務が含まれている関数、または制御フローが分かりにくい関数
• 複雑な条件分岐
• 分かりにくい命名や構造

セキュリティ原則

安全なデフォルト設定

• 認証情報やシークレットは、環境変数または専用のシークレットマネージャーで管理します
• すべてのデータベースアクセスに、パラメーター化クエリ（プリペアドステートメント）を使用します
• 言語やフレームワークが提供する、確立された暗号ライブラリを使用します
• トークン、ID、ノンスなどセキュリティ上重要な値は、暗号学的に安全な乱数生成器で生成します
• 保存時および転送時の機密データは、標準プロトコルを使用して暗号化します

入力と出力の境界

• システムの入口で、すべての外部入力について、想定される形式、型、長さを検証します。外部入力には、リクエストデータ、外部サービスの応答、モデルまたはツールの出力、書き込み元が信頼できない、または利用側がストアで保証されない内容の保証を必要とする保存データが含まれます
• 変更によって、外部コンテンツまたはモデルの出力がツールのアクション、対象、宛先を選択する境界が変わる場合、それらの値が呼び出し元にすでに許可されている操作範囲やアクセス権を超えないことを確認します
• 出力は、レンダリングされるコンテキスト（HTML、SQL、シェル、URL）に応じて適切にエンコードします
• エラー応答には呼び出し元に必要な情報のみを返し、詳細な診断情報はサーバー側でログに記録します

アクセス制御

• ユーザーデータを扱う、または状態変更を引き起こすすべての入口で認証を適用します
• 入口だけでなく、リソースにアクセスするたびに認可を検証します
• 操作に必要な権限（ファイル、データベース接続、API スコープ）のみを付与します
• アイデンティティまたは保護対象のリソースに関わる変更では、認証とリソース単位の認可のレビューを優先します

セキュリティレビューで使用する具体的な検出パターンについては、references/security-checks.md を参照してください。