In the previous chapter, we saw how to turn a code change into an explanation for learning, instead of showing it as only a diff. That explanation has another important order: show the intuition behind the change before the implementation details.
Here, intuition does not mean an unsupported impression or a feeling of “I sort of get it.” It means grasping the purpose and essence of the change in a form that you can use later when reading the code.
For example, imagine changing a garden game. If you first explain, “We want the garden to feel three-dimensional while using 2D drawing techniques,” readers can understand where the change is headed. When details about coordinates and drawing operations appear later, they can read them while thinking, “This operation is creating the sense of depth.”
講演での主張：庭を三次元に感じさせるという目標を、コードの大きなかたまりを見せる前に伝えます。
Claim in the talk: Explain the goal of making the garden feel three-dimensional before showing a large mass of code.
Figure: The explanatory heading says “Intuition before details,” and the slide shows the goal of isometric projection and the first drawing trick, “The Squashed Ellipse.”
This slide first gives an explanation of isometric projection and the drawing goal, then moves to the first trick. Therefore, it is an example of an explanation that places the concept before technical details, rather than material showing the code or the commit operation itself.
The goal of a change is different from the implementation that realizes it. The goal describes “what we want to happen.” The implementation describes “how we make it happen.”
Example: Suppose a commit message says, “Changed the rendering method.” This may accurately describe what changed. But the reader still does not know why the change was needed. If the goal “make the garden feel three-dimensional while keeping the screen flat” is shown first, it provides a frame for understanding the rendering method that follows.
This is not a matter of solving the problem by making the commit message longer. Even if the details are listed neatly, readers receive the information as disconnected pieces if they cannot see the essence of the change first. An explanation should show the intention first, and then move to the mechanism that realizes it.
Code contains a great deal of information: variables, coordinates, conditionals, and relationships among files. If readers study these without knowing the purpose, they may try to remember each part without knowing where those parts fit in the whole.
A high-level goal becomes a frame for classifying later information. It creates a view such as “this operation is related to depth” or “this one adjusts the display order.” The details are not omitted. An entry point for understanding them is created first.
For this reason, it is not appropriate to assume that a rigorous explanation must always begin with implementation details. Even if the details are arranged accurately, accuracy does not lead to understanding when readers cannot grasp the purpose. Good teaching shows the meaning of the whole first, then explains the necessary details.
The code explainer from the previous chapter explained the background of a change before moving to the actual change. For example, presenting the game engine and coordinate system first lets readers know where the change exists. The principle here takes that sequence one step further.
Background shows “what kind of system this is,” while intuition shows “what this change is trying to achieve.” When the background and goal are both present, code can be read not as a collection of strings but as a means of achieving a purpose.
This sequence makes it easier for people not only to read a change but also to build its meaning in their own minds. The later details become material for checking and making concrete that initial understanding.