structure-review

構造のレビュー

コードをレビューする際は、次の2つの点を考えます。構造の各要素は現時点で役に立っているか、そして、コードをより見つけやすく理解しやすくするために、足りない構造はないか。

構造が過剰（先を見越した抽象化や早すぎる汎用化）だと、実際の処理の流れが見えにくくなります。構造が不足（フラットなディレクトリ、責務の混在、すべてが1つのファイルまたは階層にまとまっている状態）していると、必要なコードを探すために無関係なコードまで読み進めることになります。

ワークフロー

1. 実際のコードに基づいてレビューします。

• 変更されたファイル、関連するインターフェース、および影響を受けるテストやドキュメントを読みます。
• 次のものを区別します。
  • 現在の動作を支えるために必要な構造
  • 今すぐ効果を発揮する、読みやすさを重視した構造
  • 主に仮定上の将来の利用を見越して追加された、投機的または価値の低い構造
• 完了条件：変更されたすべてのファイルを読み、いずれかのカテゴリに分類していること。

1. 過剰な構造の兆候を探します。

• 現在の動作ではほとんど使われない、追加の DB カラム、JSON フィールド、DTO プロパティ、設定キー、フック。
• 命名、再利用、不変条件、境界を改善せずに、さらに呼び出し階層を増やすヘルパーやラッパー。
• 抽象化によって隠すはずの内部詳細を、呼び出し側が依然として把握する必要がある。
• 具体的な 2 つ目の用途が見当たらない拡張ポイント、ストラテジーオブジェクト、プラグインフック、フラグ。
• 汎用性を保つことだけを目的としたマッピングオブジェクトや変換レイヤー。
• 具体的な経路が 1 つしかない概念を、複数の間接層で包んでいる。
• 実際には有効なケースが 1 つしかないオプション、列挙型、モード切り替え。
• 具体的な利用側、生成側、不変条件が必要とする前に追加された状態や永続化。
• 理解しやすさよりも探索の手間を増やすモジュール分割やディレクトリの入れ子構造。
• 将来の仮定上の作業に向けた設計により、現在の機能が追いにくくなっている。
• 完了条件：変更されたすべてのファイルとディレクトリについて、各兆候に照らして確認していること。

1. 構造が足りない兆候を探します。

• 3 つ以上の無関係な関心事にまたがる 10 個以上のファイルが、サブディレクトリでグループ化されずにディレクトリに置かれている。
• モジュールの公開 API に複数の機能が混在しており、呼び出し側が必要な機能を探すために頭の中で取捨選択しなければならない。
• 常に一緒に変更されるファイルがツリー内で離れている一方、無関係なファイルが隣接している。
• ファイルシステムのツリーからプロジェクトの主要な関心事が読み取れず、新しい読者がどこを見ればよいか予測できない。
• 単一階層のディレクトリを、明確な責務を示す 2 つか 3 つのサブディレクトリに分割できる。
• コーディングエージェントはフラットなレイアウトを選びがちです。フラットな構造を自動的に正しいと見なさず、調査すべき兆候として扱います。
• 完了条件：変更されたすべてのファイルとディレクトリについて、各兆候に照らして確認していること。

1. 構造に見合う効果があるか確認します。 追加のレイヤーが今もたらすものを考えます。

• より明確な名前や呼び出し箇所
• より強固な型境界
• より明確な所有権の境界
• 繰り返しの分岐やグルーコードの削減
• より単純な不変条件
• 扱いにくい外部の詳細の隔離
• ファイルやディレクトリの責務をより明確に理解できること

答えが乏しい、または仮定にすぎない場合は、簡素化の候補として扱います。

1. 変更のハードルを高く保ちます。

• 抽象化されているというだけで、削除を勧めないでください。
• ディレクトリにファイルが多いというだけで、入れ子構造にすることを勧めないでください。
• 明示的なコードを不当に評価しないでください。
• 読みやすさを重視した構造を無駄と見なさないでください。
• 追加の構造が継続的な保守コストを生み、実際の処理の流れを見えにくくし、または現在コードが必要としていない将来の用途のためだけに存在する場合に限り、簡素化を勧めてください。
• フラットなレイアウトによって読者が無関係なコードを頻繁に調べる必要がある場合、または責務の混在によって関心事の所在が実際に分かりにくくなっている場合に限り、再編成を勧めてください。

現在の構造を維持する目安：

• 一度しか使わないヘルパーでも、シグネチャ、名前、または呼び出し箇所の読みやすさを大きく改善している。
• 小さなオブジェクトや合成された値が関連データをまとめ、不変条件を見つけやすくしている。
• 入れ子になったモジュールやディレクトリにより、責務の所在を読者が予測しやすくなる。
• ラッパーが扱いにくい依存関係の詳細や副作用を、より明確な境界の内側に隔離している。
• 重複を少し許容するほうが共通の抽象化を設けるより低コストであり、現在の構造も局所的に明快である。
• フラットなディレクトリのファイル数が少なく、各ファイル名から目的が明確に分かる。サブディレクトリを追加しても、クリック数が増えるだけである。

出力

報告には次の構成を使用してください。

調査結果

• コードによって裏付けられる具体的な構造上の問題のみを挙げてください。過剰な構造化、不十分な構造化のどちらも対象です。
• それぞれの問題について、現在の構成がコストに見合っていない理由、または構造の欠如がナビゲーションを妨げている理由を説明してください。
• コード自体が論点の中心となる場合は、短い抜粋またはディレクトリ一覧で各問題を裏付けてください。

現状維持

• 一見すると過剰、または平坦に見えても、維持する価値のある選択を挙げてください。
• それが現時点でどのような利点をもたらしているかを説明してください。

再構成の候補

• 上記の基準を満たす変更のみを含めてください。
• 変更ごとに、次の内容を記載してください。
  • 妥当な最小限の変更（簡素化、再編成、分割、統合）
  • 削除、統合、または再グループ化されるもの
  • 得られるもの
  • 失われる可能性のあるもの
  • 今が適切なタイミングかどうか、その理由

未解決の質問

• 現在の構成を正当化し得る、明らかになっていない制約や将来の要件を列挙してください。

評価

• 次のいずれかで締めくくってください。
  • 構成は適切です
  • 小規模な再構成が妥当です
  • より広範な再編成が有効な可能性がありますが、まず制約を明確にする必要があります

抜粋のルール

• エディター形式の行番号より、本文に埋め込んだ抜粋を優先してください。
• 各抜粋の1行目には、コメントとしてソースファイルのパスを記載してください。
• 抜粋は簡潔にしてください。シグネチャ、スキーマ定義、ラッパー、設定の形式、翻訳レイヤーで通常は十分です。

コミュニケーションのルール

• 原則として、役に立つ最小限の提案にしてください。
• コードの構成がすでに適切で、無駄がない場合は、その旨を明確に述べてください。
• 懸念はもっともらしくても裏付けが弱い場合は、提案ではなく注視事項として示してください。
• レビューを有意義に見せるためだけに、簡素化の機会を作り出さないでください。