コードベース設計(Codebase Design)
ディープモジュールを設計する:小さなインターフェースの背後に多くの振る舞いを置き、それをクリーンなシームに配置し、そのインターフェースを通じてテスト可能にする。コードを設計または再構築するあらゆる場面で、この言語と原則を使用すること。目的は、呼び出し元にとってのレバレッジ、保守者にとっての局所性、そしてすべての人にとってのテスト容易性である。
用語集(Glossary)
これらの用語を厳密に使用すること — 「コンポーネント」「サービス」「API」「バウンダリ」などに置き換えないこと。一貫した言語こそがすべての要点である。
モジュール(Module) — インターフェースと実装を備えたもの。意図的にスケールに依存しない:関数、クラス、パッケージ、もしくは階層をまたぐスライス。避けること:ユニット、コンポーネント、サービス。
インターフェース(Interface) — モジュールを正しく使用するために呼び出し元が知っておくべきすべてのこと:型シグネチャだけでなく、不変条件、順序制約、エラーモード、必要な設定、パフォーマンス特性も含む。避けること:API、シグネチャ(これらは狭すぎる — 型レベルの表面のみを指す)。
実装(Implementation) — モジュールの内側、そのコード本体。アダプタ(Adapter) とは区別する:何かは、大きな実装を持つ小さなアダプタ(PostgreSQLリポジトリ)にもなり得るし、小さな実装を持つ大きなアダプタ(インメモリのフェイク)にもなり得る。シームが話題の中心であれば「アダプタ」を使い、そうでなければ「実装」を使う。
深さ(Depth) — インターフェースにおけるレバレッジ:呼び出し元(またはテスト)が、学習しなければならないインターフェースの単位あたりに発揮できる振る舞いの量。モジュールは、小さなインターフェースの背後に大量の振る舞いがある場合に深いと呼ばれ、インターフェースが実装とほぼ同じくらい複雑な場合に浅いと呼ばれる。
シーム(Seam) (Michael Feathers) — その場所で編集することなく振る舞いを変更できる場所。モジュールのインターフェースが存在する位置。シームをどこに置くかは、その背後に何を置くかとは別の設計上の決定である。避けること:バウンダリ(DDDの境界づけられたコンテキストと重複する)。
アダプタ(Adapter) — シームにおいてインターフェースを満たす具体的なもの。役割(どのスロットを埋めるか)を記述し、中身(何が内側にあるか)は記述しない。
レバレッジ(Leverage) — 呼び出し元が深さから得るもの:学習したインターフェースの単位あたり、より多くの能力。1つの実装がN個の呼び出し箇所とM個のテストに対して見返りを生む。
局所性(Locality) — 保守者が深さから得るもの:変更、バグ、知識、検証が呼び出し元全体に広がるのではなく、一箇所に集中する。一度修正すれば、どこでも修正されたことになる。
深い vs 浅い
ディープモジュール = 小さなインターフェース + 大きな実装:
┌─────────────────────┐
│ 小さなインターフェース │ ← メソッドが少なく、パラメータがシンプル
├─────────────────────┤
│ │
│ 深い実装 │ ← 複雑なロジックが隠蔽されている
│ │
└─────────────────────┘
シャローモジュール = 大きなインターフェース + 小さな実装(避けること):
┌─────────────────────────────────┐
│ 大きなインターフェース │ ← メソッドが多く、パラメータが複雑
├─────────────────────────────────┤
│ 薄い実装 │ ← 単に通過させるだけ
└─────────────────────────────────┘
インターフェースを設計するときは、次のように問いかける:
- メソッドの数を減らせないか?
- パラメータを単純化できないか?
- より多くの複雑さを内部に隠せないか?
原則(Principles)
- 深さはインターフェースの特性であり、実装の特性ではない。 ディープモジュールは内部的に、小さくモック可能で交換可能な部品で構成されていても構わない — それらは単にインターフェースの一部ではないだけである。モジュールは、内部シーム(実装に対してプライベートで、自身のテストで使用される)と、インターフェースにある外部シームの両方を持つことができる。
- 削除テスト。 モジュールを削除した場合を想像してみる。複雑さが消え去るなら、それは単なるパススルーだった。複雑さがN個の呼び出し元に再出現するなら、それは存在価値があったということだ。
- インターフェースがテストの表面である。 呼び出し元とテストは同じシームを越える。インターフェースを越えてテストしたい場合、おそらくモジュールの形が間違っている。
- 1つのアダプタは仮説上のシーム。2つのアダプタは本物のシーム。 何かが実際にそのシームをまたいで変化しない限り、シームを導入してはならない。
テスト容易性のための設計
優れたインターフェースはテストを自然なものにする:
-
依存関係を受け入れ、自分で生成しない。
// テスト可能 function processOrder(order, paymentGateway) {} // テストが困難 function processOrder(order) { const gateway = new StripeGateway(); } -
結果を返し、副作用を生み出さない。
// テスト可能 function calculateDiscount(cart): Discount {} // テストが困難 function applyDiscount(cart): void { cart.total -= discount; } -
小さな表面積。 メソッドが少ない = 必要なテストが少ない。パラメータが少ない = テストのセットアップがシンプル。
関係性(Relationships)
- モジュールは正確に1つのインターフェースを持つ(呼び出し元とテストに提示する表面)。
- 深さはモジュールの特性であり、そのインターフェースに対して測定される。
- シームはモジュールのインターフェースが存在する場所である。
- アダプタはシームに位置し、インターフェースを満たす。
- 深さは呼び出し元にとってのレバレッジと、保守者にとっての局所性を生み出す。
採用されなかったフレーミング
- 深さを実装行数とインターフェース行数の比率として捉える(Ousterhout):実装を水増しする動機を与える。代わりに、レバレッジとしての深さを採用する。
- 「インターフェース」をTypeScriptの
interfaceキーワードやクラスのpublicメソッドと捉える:狭すぎる — ここでのインターフェースは、呼び出し元が知る必要のあるすべての事実を含む。 - 「バウンダリ」:DDDの境界づけられたコンテキストと重複する。シームまたはインターフェースと言うこと。
さらに深く進むために
- 依存関係を考慮したクラスタの深化 — DEEPENING.md を参照:依存関係のカテゴリ、シームの規律、および「置き換え・レイヤー化しない」テスト。
- 代替インターフェースの探索 — DESIGN-IT-TWICE.md を参照:並行するサブエージェントを起動し、インターフェースを根本的に異なる複数の方法で設計し、その後、深さ、局所性、シーム配置について比較する。