- name
- coding-standards
- description
- コードの品質問題、アンチパターン、可読性を検査。機能実装、コードレビュー、リファクタリング時に使用。
普遍的コーディング規約
技術的アンチパターン（赤信号パターン）
以下のパターンを検出したら実装を一時停止し、該当パターン、影響を受ける現行要件、準拠できる最小の代替案、再開に必要な検証を記録する。代替案によってパターンが解消された場合、または文書化された要件によって維持する根拠を示せた場合に再開する。
コード品質のアンチパターン
- 1つの責務を、別々に保守される複数の場所に重複させた - 重複したロジックの変更理由が1つで、所有者を1つにすべきかを見直す
- 単一ファイルに複数の責務が混在 - 単一責任原則（SRP）違反
- 同じ内容を複数ファイルで定義 - DRY原則違反
- 依存関係を確認せずに変更 - 予期しない影響の可能性
- コメントアウトでコード無効化 - バージョン管理を活用すべき
- エラーの握りつぶし - 問題の隠蔽は技術的負債
- 保証の代わりに型アサーションを置く - 実行時の検査も既存の契約も裏付けていない型を宣言している
設計のアンチパターン
- 「一旦動くように」という思考 - 技術的負債の蓄積
- 継ぎ足し実装 - 既存コードへの無計画な追加
- 対処療法的修正 - 根本原因を解決しない表面的な修正
- 無計画な大規模変更 - 段階的アプローチの欠如
基本原則
ユーザー・運用者・保守者に必要な価値を届けつつ、システムの正しさと保守性を保てる、総合的な複雑性が最も低い解をエビデンスから選べる範囲まで調査する。
- 根拠で範囲を定めたリファクタリング - 現在の成果を妨げるコード、今回のタスクで変更するコード、適用対象の品質チェックに失敗するコードを、振る舞いを保つ小さなステップで改善する。それ以外の発見は、現在の変更を広げず、担当する境界と根拠を添えて報告する
- 現行要件に必要なコードだけを追加 - コードパス、機能、インフラ、抽象、起こるかどうか不明なエッジケースへの対処は、現行要件、検証済みの制約、根拠のある重大リスクが要求する場合に導入する（YAGNI）
- Design Convergence - 現在必要な成果を、追加する設計要素が最小になる形で届ける。永続状態、公開コントラクトまたは境界を越える契約、振る舞いモード、再利用可能な抽象、コンポーネント分割を導入する前に、既存機能で何を満たせるか、現行の成果に何が不足しているか、その追加が不足を埋める最小の手段である理由を記録する
総合的な複雑性は、この設計で増えるユーザーの判断・設定・モード・概念・出力・永続状態・実装経路と、それらに伴うUX・実行時・実装・テスト・文書・保守のコストで判断する。成立する案の間で実際に異なる観点だけを比較する。同じ必要な価値と証明をより低い複雑性で届けられる場合は、既存機能の再利用または新しい仕組みを追加しない案を選ぶ。
コメント記述ルール
- コードファースト: 命名・型・構造を第一の表現手段とし、コードで表現できない情報を持つときだけコメントを書く。迷ったらコメントを足す前に命名を見直す
- 「なぜ」を説明し「何を」は書かない: 判断の理由、トレードオフ、制約・エッジケース、公開APIの契約を説明する
- 現在も有効な内容: コメントには現在の判断理由、制約、エッジケース、API契約を記載し、開発履歴はバージョン管理に残す
- タイムレス: いつ読んでも有効な内容のみ記述
- 簡潔性: 必要最小限の説明にとどめる