実装の細部より先に直感を示す

前章では、コードの変更をただの差分として見せず、その変更を学ぶための説明文にする方法を見ました。その説明文には、もう一つ大切な順番があります。実装の細部より先に、変更の直感（intuition）を示すことです。

直感とは何か

ここでいう直感は、根拠のない印象や「何となく分かった」という感覚ではありません。変更の目的と本質を、後でコードを読むときに使える形でつかむことです。

たとえば、庭のゲームを変えるとします。最初に「2Dの描画技術を使いながら、庭を三次元らしく感じられるようにする」と説明すれば、読み手は変更の向かう先を理解できます。その後で、座標や描画処理の細部が出てきても、「この処理は奥行きの感じ方を作るためなのだ」と考えながら読めます。

講演での主張：庭を三次元に感じさせるという目標を、コードの大きなかたまりを見せる前に伝えます。

図：説明の見出しが「直感を細部より先に」となっており、等角投影の目標と、最初の描画上の工夫「つぶした楕円（The Squashed Ellipse）」が示されています。

このスライドは、まず等角投影（isometric projection）の説明と描画の目標を置き、その後に最初の工夫へ進む構成を示しています。したがって、コードやコミットの操作そのものを見せた資料というより、技術的な細部の前に概念を置く説明の例です。講演の該当箇所（08:28）

目標と実装は同じではありません

変更の目標は、目標を実現する実装とは別のものです。目標は「何を起こしたいのか」を表します。実装は「それをどのように起こすのか」を表します。

例：コミットメッセージに「描画方式を変更した」と書かれているとします。これは変更内容を正しく述べているかもしれません。しかし、読み手は、その変更がなぜ必要だったのかをまだ知りません。一方、「庭を平面的な画面のまま、立体的に感じられるようにする」という目標を先に示せば、後の描画方式を理解するための枠組みができます。

これは、コミットメッセージを長くすれば解決するという話ではありません。細部をきれいに列挙しても、変更の本質が先に見えなければ、読み手は情報をばらばらに受け取ります。説明では、まず意図を示し、次にその意図を実現する仕組みへ進みます。

なぜ細部を先に出さないのか

コードには、変数、座標、条件分岐、ファイルの関係など、多くの情報があります。目的を知らずにそれらを読むと、読み手は各部分を覚えようとしても、それらが全体のどこにあるのか分かりません。

高いレベルの目標は、後の情報を分類するための枠になります。「この処理は奥行きに関係する」「これは表示の順番を調整している」といった見通しを作れるからです。細部を省くのではありません。細部を理解するための入口を先に作るのです。

そのため、厳密な説明は必ず実装の詳細から始めなければならない、という考え方は適切ではありません。詳細を正確に並べても、読み手が目的をつかめなければ、正確さは理解につながりません。良い教え方では、先に全体の意味を示し、必要な細部をその後で説明します。

前章の説明文とのつながり

前章で扱ったコード・エクスプレーナーは、変更の背景を説明してから、実際の変更へ進むものでした。たとえばゲームエンジンや座標系などを先に置くと、読み手は変更が存在する場所を知ることができます。今回の原則は、その流れをさらに一歩進めます。

背景が「このシステムはどのようなものか」を示すのに対し、直感は「今回の変更は何を目指しているか」を示します。背景と目標がそろうと、コードは単なる文字列の集まりではなく、目的を実現する手段として読めます。

この順番によって、人は変更を読むだけでなく、変更の意味を自分の中で組み立てやすくなります。後の細部は、その最初の理解を確かめたり、具体化したりする材料になります。