codebase-stewardship

コードベースの保守

次の変更が、すでに存在するコードベースになじむようにします。

まずローカルのパターンを把握する

新しい動作を追加する前に、近くにあるコードや類似するコードを確認し、次の点を把握します。

• 命名スタイルとドメイン用語。
• ファイルの配置と公開エクスポート。
• データフローと状態の管理元。
• エラー処理とバリデーションのスタイル。
• テストのスタイルとフィクスチャの規約。
• 既存の拡張ポイントや抽象化。

別のパターンも単独では妥当であっても、ローカルのパターンを優先します。

並行する仕組みを作らない

タスクで旧方式の置き換えが明示されていない限り、同じことをする別の方法を作らないでください。

要注意の兆候：

• 新しいヘルパーが既存のヘルパーと機能が重複している。
• 新しいサービス、フック、アダプター、コマンド、コンポーネントが、既存の役割と重複している。
• 新しいコードで同じ概念に新しい名前が付けられている。
• 新しい設定やフラグが、既存の機能を迂回している。
• 近くのテストでは共有フィクスチャが使われているのに、新しいテストでは独自のセットアップが必要になっている。

重複がある場合は、競合する経路を新設するのではなく、確立されたインターフェースを拡張または調整します。

ドメイン概念を安定させる

名前を変えることは、システムの言葉を変えることです。変更依頼が名前の変更である場合、または現在の変更内容に対して旧名が明らかに誤解を招く場合に限り、名前を変更します。

次の項目には、既存のドメイン用語を使います。

• 型とインターフェース。
• API フィールド。
• イベントとコマンド。
• テスト名。
• エラー名。
• ファイル名とディレクトリ名。

新しい用語が必要な場合は、既存の用語体系との関係を明確にします。

レビューしやすい経緯を残す

変更によって新しいパターンが導入される場合や、既存のパターンが拡張される場合は、判断を容易に検証できるようにします。

• 準拠する既存のパターンを示します。
• なぜその拡張がその場所に適しているのかを説明します。
• 例とテストで同じ用語体系を使います。
• 保守上の判断と、関係のない整理を混在させないでください。

完了の基準

変更が既存のコードベースの特性になじんでいること。最も近いローカルのパターンに従い、重複する仕組みを避け、名前の変更が必要でない限りドメイン用語を維持し、可能な限り確立されたインターフェースを拡張し、必要な新しいパターンを明確にしてレビュー可能な状態にします。