説明付きコード差分で変更を読みやすくする

In the previous chapter, we saw that when code is shown as part of an explanation, it is important not to enter the details immediately, but first to show the intuition behind the change—the kind of change it aims to achieve. This chapter covers how to move on to the actual code changes while keeping that intuition.

It is hard to reconstruct a change's meaning from a raw diff alone

Code reviews often use a diff. A diff displays added and deleted lines. However, if readers receive only a list of changed files and line differences, they must infer the following things for themselves.

• Which file should they read first
• What role does each file play in the change as a whole
• How does a change read earlier connect to a later change

In other words, a raw diff contains information, but it does not teach readers how to read it. Even when every line is visible, the structure of the change may not be visible.

What is a literate code diff?

The speaker presents a literate code diff. This is not a different kind of version-control diff. It is a code change organized with explanatory prose and an intentional order so that it is easier to read.

First, explain the purpose of the change as a whole in a short passage. Then take up each file in an intentional order. Before showing a file's code, explain what happens in that file and why it is needed for the change as a whole. The reader can use the explanation as a guide while reading the code.

Figure: An example of a literate code diff that presents explanatory headings and prose together with code blocks. The scene where the speaker explains this idea can be found at YouTube 00:09:36.

What this figure shows is a structure that places explanations before and after the code instead of lining up code alone. As a result, readers can think not only about the fact that a line changed, but also about where that change belongs in the whole. The figure is a presentation slide illustrating the idea; the exact layout of the actual document and the files used cannot be confirmed from this video.

Design the reading order

The central point of this method is to arrange each file, with an explanation, in a meaningful order. Abstracted into steps, it looks like this.

1. Explain the purpose of the change and the result it aims for.
2. Explain the role the first file plays in the change as a whole.
3. Immediately after that explanation, show the relevant code diff for the file.
4. Before moving to the next file, explain how the changes so far connect to the next change.
5. Continue in the same flow until the last file.

With this order, the reader's understanding builds little by little. With a list containing only file names, the reader has to discover the order independently. With an explained order, the background gained earlier prepares the reader for the next part.

Example: a raw diff and an explained diff

A raw diff can be presented like this, for example.

From this list alone, it is not clear which file is the starting point or which file displays the result. The reader opens the files and reconstructs the relationships between the code independently.

An explained presentation might guide the reader as follows, for example. This is an example created by the teacher to make this chapter's idea easier to understand. It does not mean that the speaker actually used these file names or this order.

In this example, the code lines themselves have not been reduced. Because the purpose and relationships are shown first, readers can read each diff not as an isolated change, but as one stage in achieving a single transformation.

Read a pull request like a textbook

The speaker explains that this structure lets people read a pull request like a textbook. Here, “like a textbook” does not only mean making the format neat. It means showing the prerequisites and purpose, creating an order, and moving toward the details as a textbook explanation does.

This also connects to the individual code explanations discussed in the previous chapter. When an agent creates a change, do not stop at the raw diff. Create a personalized explanation for understanding the change, and include the background, intuition, and explained code diff in it. The speaker says that he read the result not only on the IDE (integrated development environment) screen, but also in print. A format that can be reread away from the screen can also help the change become part of one's own understanding.

An important distinction: a diff does not explain itself automatically

It is a common misunderstanding of this method to think, “The diff contains all the changed lines, so no explanation is needed.” A diff is good at showing what changed. A literate code diff, on the other hand, shows why it changed, in what order it should be understood, and how it relates to other changes.

This difference concerns not only checking correctness, but also understanding for participation. Following each line of code alone places a heavy burden on the reader before they can grasp the change as a whole. When an explanation comes first, people have a map of the change before reading the code details. Using that map in review makes it easier to raise the next question or idea, rather than merely approving the change.

For the Zen-garden change shown by the speaker, the video explanation establishes that the explanatory document connects the background of the change with the code. The specific arrangement of the diff and the details of the files actually changed cannot be confirmed from the provided information. This chapter therefore focuses on the confirmed idea and does not fill in implementation details.