engineering-quality

エンジニアリング品質

読みやすく、デバッグしやすく、誤用しにくい、シンプルなコードを優先します。

奇抜さより明快さを選ぶ

まず、次の保守担当者が理解しやすいことを重視します。名前、中間値、制御フローが明確になるなら、実装が多少長くなっても構いません。

奇抜な抽象化や密度の高い式を選ぶ前に、次の点を確認してください。

• これは現在の問題を解決するものですか。それとも、まだ必要のない将来の問題を想定したものですか。
• 直接的な実装のほうがレビューしやすくありませんか。
• この抽象化は、本当の複雑さを隠していますか。それとも、単に別の場所へ移しているだけですか。

コメントでは「何を」ではなく「なぜ」を説明する

コメントでは、コードだけでは表現できない背景を説明してください。

• 自明でないビジネス上の判断。
• セキュリティやプライバシー上の制約。
• パフォーマンス上のトレードオフ。
• 回避する問題を含めた回避策。
• 意外な順序が必要な理由。

次の行のコードを言い換えているだけのコメントは削除してください。代わりに、名前や構造を改善してください。

失敗をデバッグしやすくする

エラーには、失敗した操作と重要な背景を示します。ただし、秘密情報や機密データを漏らしてはいけません。

エラーから、次の点が分かるようにしてください。

• システムは何をしようとしていましたか。
• 関連する安定した識別子または入力は何ですか。
• 無効な入力、欠落した状態、禁止されたアクセス、外部要因による失敗のどれですか。

トランスポート固有のエラークラスは、トランスポート境界に留めてください。低レベルのコードでは、外部向けに変換できるドメインエラーまたはアプリケーションエラーを発生させてください。

ローカルなリファクタリングは権限の範囲内に留める

正確性のため、または変更対象の処理経路を理解しやすくするために必要な場合は、その経路内で小規模なリファクタリングを行います。必要なローカルな補助と便乗的な改善の区別については、/agentic-change-governance に従ってください。単に近くにあるだけでは、変更する権限があることにはなりません。

明示的に依頼されていない限り、任意の整理、スコープの拡大、変更対象の動作範囲外の作業は後回しにしてください。

アルゴリズムの構造に注意する

10 個の項目では問題なく動くコードでも、本番環境の規模では破綻することがあります。ネストしたループ、クエリの繰り返し、解析の繰り返し、広範なデータ取得は、設計上の判断として扱ってください。

繰り返しの検索や照合が本質的な処理である場合は、マップ、セット、インデックス、バッチ処理、事前計算を優先してください。

完了の基準

コードは仕組みを解読しなくてもレビューできるほど明快であり、コメントは自明でない背景だけを説明し、エラーには有用かつ安全な背景情報が含まれ、変更対象の処理経路で必要なリファクタリングは合意された範囲内に収まり、アルゴリズムの構造は想定される規模に対して妥当です。