coding-standards

# 普遍的コーディング規約 ## 技術的アンチパターン（赤信号パターン） 以下のパターンを検出したら実装を一時停止し、該当パターン、影響を受ける現行要件、準拠できる最小の代替案、再開に必要な検証を記録する。代替案によってパターンが解消された場合、または文書化された要件によって維持する根拠を示せた場合に再開する。 ### コード品質のアンチパターン 1. **同じようなコードを3回以上書いた** - Rule of Threeに違反 2. **単一ファイルに複数の責務が混在** - 単一責任原則（SRP）違反 3. **同じ内容を複数ファイルで定義** - DRY原則違反 4. **依存関係を確認せずに変更** - 予期しない影響の可能性 5. **コメントアウトでコード無効化** - バージョン管理を活用すべき 6. **エラーの握りつぶし** - 問題の隠蔽は技術的負債 7. **型アサーション（as）の多用** - 型安全性の放棄 ### 設計のアンチパターン - **「一旦動くように」という思考** - 技術的負債の蓄積 - **継ぎ足し実装** - 既存コードへの無計画な追加 - **不確実技術の楽観的実装** - 未知要素を「たぶん動く」前提で設計 - **対処療法的修正** - 根本原因を解決しない表面的な修正 - **無計画な大規模変更** - 段階的アプ��ーチの欠如 ## 基本原則 広く探索したうえで、システムの正しさと保守性を保ちながら、ユーザー・運用者・保守者に必要な価値を届けるライフサイクルコスト最小の解へ収束させる。 - **根拠で範囲を定めたリファクタリング** - 現在の成果を妨げるコード、今回のタスクで変更するコード、適用対象の品質チェックに失敗するコードを、振る舞いを保つ小さなステップで改善する。それ以外の発見は、根拠とともにスコープ判断へ回す - **現行要件に必要なコードだけを追加** - コードパス、機能、インフラ、抽象、起こるかどうか不明なエッジケースへの対処は、現行要件、検証済みの制約、根拠のある重大リスクが要求する場合に導入する（YAGNI） - **Design Convergence** - 現行の必要な成果を、新規の設計サーフェスが最小になる形で届ける。永続状態、公開コントラクトまたは境界を越える契約、振る舞いモード、再利用可能な抽象、コンポーネント分割を導入する前に、既存の能力で何が届いているか、現行の成果に対して何が届い��いないか、そしてその追加がその差を埋める最小のものである理由を記録する ## コメント記述ルール - **コードファースト**: 命名・型・構造を第一の表現手段とし、コードで表現できない情報を持つときだけコメントを書く。迷ったらコメントを足す前に命名を見直す - **「なぜ」を説明し「何を」は書かない**: 判断の理由、トレードオフ、制約・エッジケース、公開APIの契約を説明する - **現在も有効な内容**: コメントには現在の判断理由、制約、エッジケース、API契約を記載し、開発履歴はバージョン管理に残す - **タイムレス**: いつ読んでも有効な内容のみ記述 - **簡潔性**: 必要最小限の説明にとどめる ## エラーハンドリングの基本原則 ### Fail-Fast原則 エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ。元の診断情報を保持したまま失敗を伝播するか、明示的な型付きエラーを返す。 詳細な実装方法（Result型、カス...