Lesson 0002 · Phase 1 — 複雑性とコードベース設計
0001で目盛りを渡した。今回はその目盛りで実コードを測れるようにする。「なんか汚い」を「ここが情報漏れ」に変える検査キットの回。
複雑性の原因は2つだけ、と0001で言った。でも抽象的すぎて現場で使えない。具体的な現れ方に翻訳しよう1。
覚え方: 依存 = 変更が伝播する/不明瞭さ = 知識が隠れる。レビュー中はこの2語で必ず指させる。
原因を、もっと鋭いパターンに分解したのがレッドフラグ2。コードを見て名前が即出るまで体に入れる。各フラグ=依存か不明瞭さの"具体形"だよ。
インターフェースが実装と同じくらい複雑。包んでるだけで何も隠していない=価値ゼロ。
# ただ素通しするだけ。抽象になっていない(不明瞭さは減らない) class TextBox: def get_text(self): return self._w.get_text() def set_text(self,t): self._w.set_text(t)
1つの設計判断(例: 日付の形式)が複数モジュールに反映されている。片方を変えると、もう片方も壊れる=依存。
# parser.py d = parse("%Y-%m-%d", raw) # formatter.py … 同じ "%Y-%m-%d" の知識が2箇所に漏れている out = fmt("%Y-%m-%d", d)
引数を別メソッドに渡すだけで何もしない。層が増えるのに抽象は増えない(情報漏れの一種)。
class OrderController: def create_order(self, data): return self.service.create_order(data) # 素通し
構造を実行順(読む→処理→書く)で割ってしまう。読みと書きが共有する「形式」の知識が3つに散る=情報漏れ。情報隠蔽で割るのが正解。
class FileReader: ... # step1 class FileParser: ... # step2 class FileWriter: ... # step3 ← 形式の知識が3クラスに分散
よく使う機能のために、めったに使わない概念まで知らされる。一番多いケースが一番簡単であるべき。
# ただ読むだけなのに3つの概念を知らされる
r = StreamReader(BufferedStream(FileStream(path)), Charset.UTF8)
汎用の仕組みの中に特定用途のコードが混ざる。あるいは2つのメソッドが片方だけでは理解できないほど絡む=依存。
スニペットを読んで、最も当てはまるフラグを選んで。押すと即フィードバック。
致命的な事実をもう一度。複雑性は一撃では死なない。少しずつ積もる。だから1個1個は「まあいいか」で通ってしまう ── そして気づくと沼1。
運用の3原則 ──
1. 触ったら、設計を良くして去る。 Ousterhout 曰く「変更時に設計を良くしていないなら、たぶん悪くしている」1。
2. でも"全部書き直す"ではない。 既存の慣習をむやみに"改善"しない ── 一貫性も立派な設計価値1。zero tolerance は新しい複雑性を足さない+触れた範囲を少し良くすること。
3. レッドフラグを足さない。 新規コード/AI出力をマージする前に、上のカタログでスキャン。1つでも当たれば、その場で直すか理由を残す。
場面: 既存の PaymentService にAIが新メソッドを足した。読むと、決済プロバイダの仕様(手数料率の計算式)が、この新メソッドと既存の Invoice の両方に書かれていた。あなたの最も zero-tolerance な動きは?
用語は ../GLOSSARY.md、検査キット早見表は ../reference/0002-red-flags-checkkit.html。
次回 0003: レッドフラグの裏返し=深いモジュールを自分で設計する。