判断の軸を、コードの外に逃がさない

判断の軸が重要だ、
という話までは、
多くのエンジニアが同意します。

問題は、その次です。

判断の軸は、
どこに置けばよいのでしょうか。

頭の中でしょうか。
設計ドキュメントでしょうか。
コードでしょうか。

この章では、
判断の軸を「消えにくい形」で残す方法を考えます。

軸が失われる一番の理由

判断の軸が失われる理由は、
実はとても単純です。

軸が、コードの外にあるからです。

  • ドキュメント
  • Wiki
  • 設計資料

それらは悪ではありません。

しかし、
コードと更新タイミングがズレた瞬間、
信頼されなくなります。

結果として、
人はコードだけを見るようになります。

そしてコードの中に、
判断の理由が見つからなくなります。

判断は「読む人が必ず通る場所」に置く

判断の軸を残すための原則は、
一つだけです。

読む人が、必ず通る場所に置くこと。

誰も読まないドキュメントに、
重要な判断を書いても意味はありません。

一方で、
必ず読まれる場所があります。

それは、
コードです。

正確には、
コードを理解するために、
必ず目に入る構造です。

命名は、判断を閉じ込める最初の手段

もっとも軽く、
もっとも効果的な方法は、
命名です。

なぜこのクラスが存在するのか。
なぜこの責務が切り出されているのか。

それが名前に現れていれば、
読む人は自然に軸を追えます。

逆に、
無難で抽象的な名前は、
判断を隠します。

  • Manager
  • Helper
  • Util

これらは、
判断を先送りにした結果です。

命名は、判断を固定する行為です。

層を作ることは、判断の担当を決めること

レイヤー分割も、
判断を残すための手段です。

どこで判断するのか。
どこでは判断しないのか。

それを、
構造として固定します。

UI は判断しない。
UseCase が判断する。
Repository は選択肢を提供する。

こう決めることで、
判断は散らばりにくくなります。

層とは、判断の責任範囲です。

コメントを書くなら「なぜ」だけを書く

コメントを書く場合、
注意点があります。

やっていることを書く必要はありません。
コードを読めば分かるからです。

書くべきなのは、
なぜ、そうしているのか です。

なぜこの条件があるのか。
なぜこの分岐はここにあるのか。
なぜ別の選択をしなかったのか。

コメントは、
判断の補助線として使います。

テストは、判断を固定する最後の砦

テストもまた、
判断を残す場所です。

何を保証しているのか。
何を保証しないのか。

それが、
テストケースとして表れます。

特に、
境界条件や例外系は、
強い判断の塊です。

なぜこのケースを落とすのか。
なぜここは通してよいのか。

テストは、判断を軽く書き換えられないようにする仕組みです。

判断を書かない設計は、必ず口頭説明に戻る

判断がコードに残っていない場合、
どうなるでしょうか。

必ず、
口頭説明に戻ります。

「それは暗黙の了解で」
「前からそうなっていて」
「触るときは気をつけて」

こうした言葉が増えたら、
判断は失われています。

設計が属人化しているのではありません。
判断が、構造に閉じていないだけです。

この章のまとめ

判断の軸は、
意識しないと必ず消えます。

だからこそ、
消えにくい場所に置く必要があります。

  • 命名
  • 構造
  • コメント
  • テスト

これらはすべて、
判断を固定するための手段です。

次の章では、
既に判断が失われたコードに対して、
どうやって軸を見つけ直すのか を扱います。

つまり、
モノリスや負債のある現場で、
最初に何を見るべきか、です。