Lesson 0003 · Phase 1 — 複雑性とコードベース設計

深いモジュール
— インターフェースを "薄く"、中身を "厚く"

0002ではレッドフラグで汚さを名指しできるようになった。今回はその裏返し。「良い設計」を1つの物差し ── 深さ(depth) ── で測り、自分で設計できるようにする。

🎯 ミッション接続: 曖昧な要求を設計に落とすとき、あなたが分割する単位=モジュールの質が全体を決める。 「深いモジュールを設計できる」=AIに正しい構造を指示できるし、AIが吐いた浅い構造を矯正できる。今日「深さ」という一本の物差しを持ち帰る。
復習: 複雑性 = 依存 + 不明瞭さ レッドフラグ Shallow module 処方 zero tolerance

01 — モジュールを2枚に分けて見る

インターフェース と 実装

どんなモジュール(関数・クラス・サービス)も、2つの部分でできてる1。ここを分けて見るのが、今日の全ての土台だよ。

インターフェース interface

  • 使う側が知らなきゃいけないこと
  • 形式的: 引数・返り値・型(シグネチャ)
  • 非形式的: 呼ぶ順序・前提・副作用などシグネチャに出ない約束事

実装 implementation

  • その内側で実際にやっていること
  • 使う側は知らなくてよい
  • ここに複雑さを閉じ込めるのが仕事

キモは非形式的インターフェース。型に出ない「先に◯◯を呼んでおくこと」「例外時はこうなる」みたいな暗黙の約束が多いほど、使う側の認知負荷が上がる ── これが 0002 の「不明瞭さ」の正体だったね。

02 — 深さ という物差し

最高のモジュールは「厚い中身」を「薄い窓口」で渡す

Ousterhout の中核テーゼ: モジュールは深くあれ(modules should be deep)1。深さは、次の比で決まる。

深さ = 提供する機能(=隠す複雑さ) ÷ インターフェースの複雑さ
大きいほど良い。小さな窓口で、大きな仕事を隠せているほど"深い"。

深いモジュール ◎

薄いインターフェース
厚い実装
(多くの機能を隠す)

窓口は小さいのに、大量の複雑さを飲み込む。コスト<利益。

浅いモジュール ✕

分厚いインターフェース
薄い実装

窓口が実装と同じくらい複雑。包んだ意味がない。コスト≒利益。

古典的な"深い"例が Unix のファイルI/O1。窓口は open / read / write / close / lseek の実質5個だけ。その裏で、ディスクブロック割り当て・ディレクトリ探索・権限・キャッシュ・並行アクセスといった膨大な複雑さを隠してる。薄い窓口 × 厚い中身=深いモジュールの手本。

Practice · どっちが深い?

2つの設計を比べて、より深い方を選んで。押すと即フィードバック。

03 — 深さを殺す最大の敵

"classitis":クラスは小さいほど良い、という誤信

「クラス/関数は小さく分けるほど良い」── よく聞くよね。でもこれを突き詰めると、浅いモジュールが大量に増える。Ousterhout はこの症候群を classitis と呼ぶ2。

なぜダメか: モジュールを1個増やすたびに、新しいインターフェース=新しい学習コスト=新しい依存が生まれる。細かく割りすぎると、部品同士の連結を理解するコストが、隠したはずの複雑さを上回る。「短い」と「単純」は違う2。

総複雑性 = Σ(各モジュール内部の複雑さ)+ Σ(モジュール間の連結の複雑さ)
分割を増やすと左項は減るが右項が増える。深さは、この総和を最小化する分け方を選ぶこと。

だから設計判断はいつも「この線引きは、隠す複雑さ > 増える連結コスト か?」。答えが No なら、その分割はしない方がいい。2つの浅いクラスを1つの深いクラスに統合するのも立派な設計判断だよ。

AI時代の効き目: AIは頼むと小さなクラス/関数を量産しがち(classitis のデフォルト生成器)。 見た目は「きれいに分割された」風だけど、実体は浅いモジュールの群れ=連結地獄なことが多い。 あなたが「深さ」で測れると、"分けすぎ"を名指しして「ここは統合して1つの深いモジュールに」と正しく指示・矯正できる。
Practice · 深く設計し直す

場面: AIが「設定読み込み」をこう分けてきた。使う側はA→B→Cを正しい順序で自分で呼ぶ必要がある。あなたの最も"深い"直し方は?

class ConfigFileOpener:   # A: ファイルを開くだけ
class ConfigParser:       # B: 文字列→dict にするだけ
class ConfigValidator:    # C: dict を検証するだけ
# 呼ぶ側: open→parse→validate を毎回手で繋ぐ

04 — でも「深く」を言い訳に太らせない

深い ≠ なんでも詰め込む

逆張りの罠も1つ。「深くしろ」を「1クラスに全部入れろ」と勘違いすると、神クラスができる。深さの条件は薄い窓口とセット。機能が凝集していて、かつ窓口が小さいときだけ深い。関係ない責務を同じモジュールに混ぜたら、それは 0002 の special-general mixture に逆戻りだよ1。

合言葉: 「窓口は小さく、中身は厚く、責務は1つに凝集」。3つ揃って初めて深い。

🚀 今週の一手(原則 → 実コード)

  1. 自分のコード or 直近のAI出力から、クラス/モジュールを3つ選ぶ。
  2. 各モジュールのインターフェースの行数(公開メソッド+暗黙の約束の数)を数える。ざっくりでOK。
  3. 「この窓口の広さに対して、隠している複雑さは見合ってる?」を各モジュールに◎/△/✕で採点。
  4. ✕(浅い)を1つ選び、隣のモジュールと統合して深くできないかを1案スケッチ。
  5. その1案をこの会話に貼って。深さの判定、一緒に精度上げよう。
💬 先生(このAIエージェント)に聞いてね。 「このクラス、深い?浅い?」「この2つ、統合すべき?分けるべき?」「AIが分割しすぎてない?」── 実コードを貼ってくれたら、その場で「深さ」の物差しを当てて、窓口と中身の比を一緒に見積もるよ。これがあなたの最速フィードバックループ。
出典 / Sources
  1. John Ousterhout, A Philosophy of Software Design — モジュール=インターフェース+実装(Ch.4)、「modules should be deep」/深さの定義/Unix I/O の例(Ch.4)、special-general mixture(Ch.9)。
  2. danlebrero — A Philosophy of Software Design book notes(classitis/「short ≠ simple」/深いモジュールの要約) / 補助: The Pragmatic Engineer — interview with Ousterhout。

用語は ../GLOSSARY.md、早見表は ../reference/0003-depth-card.html。 次回 0004: 深さを支える技術=情報隠蔽と「漏れる抽象」。何を窓口に出し、何を中に隠すかの線引き。