書く練習は強制され、読む練習はされない
仕事でコードを書けば、結果は強制的に採点されます。動くか動かないか、レビューを受け、リリースされます。うまく書けなければ表に出ます。
読みはそうではありません。雑に読んでも誰も気づきません。理解したふりをして隣に書き足せばたいてい動き、問題が出るとしても数か月後で、そのときには原因が読みの浅さだったとは見えません。
こうして読みは、誰もが毎日やりながら誰も訓練しない技術になりました。そしてこの非対称の上に最近の変化が乗りました。自分の手で書いていないコードがリポジトリに入る量が増えたのです。コードを作り出す能力の相対的な値が下がるほど、他人が作ったものを読んで判定する能力の値は上がります。
コードに残らないもの
読みが難しい根本の理由は、コードが決定の結果だけを残し、決定の過程を残さないからです。
コードは採用された案を一つだけ見せます。検討して捨てた三つの代案、捨てた理由、当時かかっていた制約、この形を強いた外部システムの事情は、どこにもありません。だから読む人は「なぜこんなに変な形なのか」で止まり、たいていその変さには理由がありました。
Fred Brooksが1986年の「No Silver Bullet」で立てた区分がここで役に立ちます。彼はソフトウェアの複雑性を偶有的複雑性と本質的複雑性に分け、道具が改善するのは偶有的なほうで、本質的複雑性は問題そのものから来るので取り除けないとしました。彼の主張は、どんな単一の発展も十年で十倍の改善を約束しないというものでした。
この区分を読みに当てはめるとこうなります。文法や慣用表現は偶有的複雑性で、道具の助けをよく受けます。一方、このドメインがなぜこの規則を持つのか、なぜこの二つのシステムはこの順序でしか会話できないのかは本質的複雑性で、テキストだけからは復元できません。読みの訓練が向かうのは後者です。
大規模コードベースに入る七つの手順
初めて見るリポジトリには順序があります。順序を守るだけで最初の一週間が大きく変わります。
- まず動かします。 ビルドし、起動し、ヘルスチェックを通します。動かせない状態で読むのはすべて推測です。この段階で詰まった箇所が、そのままシステムの隠れた依存の一覧になります。
- 入口を探します。 ルート定義、メッセージのコンシューマ、スケジューラの登録簿。ここが地図の海岸線です。
- リクエスト一本を最後まで追います。 広く眺めず、一本を縦に貫きます。最も単純な参照リクエスト一つで十分です。この一往復で階層構造と命名規則とエラー処理の慣習が一度に入ってきます。
- データモデルを見ます。 スキーマと移行履歴はドメインの化石です。カラムが追加され名前が変わった痕跡は、業務がどう変わってきたかをコードより正直に語ります。
- テストを仕様として読みます。 テストは、このチームが何を守るべきと信じているかの一覧です。テストのない領域は、誰も契約を決めなかった領域です。
- 変更密度を見ます。 よく変わるファイルが危ない場所であり、同時に重要な場所です。
- 自分の言葉で書き直します。 一枚の要約を作り、分かっている人に見せて誤りを指摘してもらいます。この段階を飛ばすと、前の六つが未検証のまま残ります。
# 例 — 直近一年で最も頻繁に変わったファイル上位20件
git log --since=1.year --name-only --pretty=format: \
| grep -v '^$' | sort | uniq -c | sort -rn | head -20
この一覧の上のほうから読むと、投入時間あたりの理解が最も速く上がります。よく変わるとは要求がよく届くということで、要求がよく届く場所がそのシステムの心臓です。
文書のないシステムは、稼働中の自分自身が文書です
文書のないシステムに当たると、人はまずソースを掘ります。順序が逆であることが多い。稼働中のシステムは自分自身についての最も新しい文書です。コードはリリースされていないかもしれませんが、今動いているプロセスは嘘をつきません。
観測から始めるとこういうものが先に出ます。どのポートが開いていて誰と接続を張っているか、どの環境変数と設定が実際に注入されているか、どのログがどの頻度で出るか、どのスケジュールが何時に回るか。ここまででシステムの境界と外部依存が描けます。
その後にコードへ入ると、読む目的が生まれます。目的なく読めばファイル一覧を眺めて終わり、「この接続はなぜ張られているのか」を持って入れば必要な箇所だけを正確に読みます。
罠を一つ先に書いておきます。リポジトリにあることは生きていることではありません。死んだコードを読むのに数日を使うことは思ったより頻繁に起きます。読む前に「今ここをトラフィックが通っているか」を確かめてください。ログ一行、呼び出しカウンタ一つで答えが出ます。
読みがなぜ高い側に残るのか
このシリーズの判別式に戻ると、読みは検証コストの高い側に確実に属します。理由が二つあります。
一つは、読みの産物が理解であり、理解は直接検査できないことです。検査するには理解を外に出さねばなりません。要約を書くか、説明するか、予測して当たるかを見るかです。だから読みを訓練するには必ず出力を付ける必要があり、七番目の手順が選択肢でない理由がここにあります。
もう一つは前述の本質的複雑性です。読むべきものの相当部分がコードの外にあり、それを持つ人に尋ねねばなりません。何を尋ねるべきかを知ること自体が読みの成果なので、この能力はテキスト処理能力ではなく、組織の中で情報を取りにいく能力と結びついています。
手を動かす
今週、他人が書いてマージされたプルリクエストを一つ選んでください。そして五つの文で要約します。何を変えたか、なぜ変えたか、どんな代案がありえたか、何が壊れうるか、まだ分からないことは何か。それを作成者に送り、誤りを尋ねてください。最後の一文が最も価値のある質問を作ってくれます。
- Git 練習場 — 履歴を掘り、戻し、二分するといった操作を、実際のリポジトリを壊す心配なく反復できます。
- 論理トレーニング — 他人の論証を正確に再構成する練習です。他人のコードを読むのと同じ筋肉を使います。
通じない場合もあります。まもなく廃止されるシステムなら、深く読むのは無駄です。そのときは理解ではなく境界だけを掴めば足ります。何が入り何が出るかさえ分かれば差し替えられます。
続けて読む
- このブログの関連記事: 教えるコードレビュー、傷つけるコードレビュー — 同じ指摘の結果を分けるもの
高いまま残る技術シリーズ
参考資料
- No Silver Bullet — Wikipediaの要約 — Fred Brooksが1986年に示した偶有的複雑性と本質的複雑性の区分、および十年で十倍の改善を約束する単一の発展はないという主張。2026-08-15閲覧。
- 七つの手順と観測優先の読み解き順序は上記資料にあるものではなく、この記事で整理したものです。
현재 단락 (1/35)
仕事でコードを書けば、結果は強制的に採点されます。動くか動かないか、レビューを受け、リリースされます。うまく書けなければ表に出ます。