9:32 - 10:09

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

この時点から動画を見る

前の章では、説明の中でコードを見せるとき、いきなり細部へ入らず、まず変更の直感（どのような変化を目指したのか）を示すことが大切だと見ました。この章では、その直感を保ったまま、実際のコード変更へ進む方法を扱います。

生の差分だけでは、変更の意味を組み立てにくい

コードレビューでよく使うのは、差分（diff）です。差分には、追加された行や削除された行が表示されます。しかし、変更されたファイルの一覧と行の差分だけを渡されても、読者は次のことを自分で推測しなければなりません。

どのファイルから読むべきか
それぞれのファイルが、変更全体の中で何を担当するのか
先に読んだ変更が、後の変更とどうつながるのか

つまり、生の差分は情報を含んでいますが、読み方までは教えてくれません。すべての行が見えていても、変更の構造が見えるとは限りません。

リテラシー付きコード差分とは何か

話者が示すのは、**リテラシー付きコード差分（literate code diff）**です。これは、バージョン管理の差分とは別の形式の差分ではありません。コードの変更を、説明文と順序で読みやすく整理したものです。

まず、変更全体の目的を短い文章で説明します。その後、各ファイルを意図的な順番で取り上げます。各ファイルのコードを見せる前には、「このファイルでは何が起きるのか」「変更全体の中でなぜ必要なのか」を説明します。読者は、説明を手がかりにしてコードを読み進められます。

説明文とコードを組み合わせた「Literate code diffs」のスライド

図：説明の見出しや文章と、コードブロックを一緒に示すリテラシー付きコード差分の例です。話者がこの考え方を説明する場面は、YouTubeの00:09:36から確認できます。

この図が示しているのは、コードだけを並べるのではなく、コードの前後に説明を置く構成です。したがって、読者は「この行は変更された」という事実だけでなく、「この変更は全体のどの部分なのか」も考えやすくなります。図は考え方を示すプレゼンテーション資料であり、実際の文書の正確なレイアウトや使用されたファイルまでは、この映像から確認できません。

読む順番を設計する

この方法の中心は、各ファイルを説明付きで、意味のある順番に並べることです。手順を抽象化すると、次のようになります。

変更の目的と、目指す結果を説明します。
最初のファイルが変更全体で果たす役割を説明します。
その説明の直後に、そのファイルの関連するコード差分を示します。
次のファイルへ進む前に、ここまでの変更が次の変更とどうつながるかを説明します。
同じ流れで、最後のファイルまで進みます。

この順番では、読者の理解が少しずつ積み上がります。ファイル名だけのリストでは、読者がその順番を自分で発見しなければなりません。説明付きの順番なら、前の部分で得た背景が、次の部分を読むための準備になります。

例：生の差分と説明付きの差分

生の差分の見せ方は、たとえば次のようになります。

変更されたファイル
- scene.ts
- renderer.ts
- coordinates.ts

この一覧だけでは、どのファイルが出発点で、どのファイルが結果を表示するのか分かりません。読者はファイルを開き、コードの関係を自分で再構成します。

説明付きの見せ方では、たとえば次のように案内します。これはこの章の考え方を分かりやすくするための教師作成の例です。話者が実際にこのファイル名や順番を使ったという意味ではありません。

まず、座標の扱いを変えます。
この変更で、次の描画処理が新しい位置を使えるようになります。

→ coordinates.ts の関連する差分

次に、その座標を画面上の見え方へ反映します。

→ renderer.ts の関連する差分

最後に、シーンから新しい描画処理を呼び出します。

→ scene.ts の関連する差分

この例では、コードの行そのものを減らしていません。先に目的と関係を示しているため、読者は各差分を「単独の変更」ではなく、「一つの変化を実現する段階」として読めます。

プルリクエストを教科書のように読む

話者は、この構成によってプルリクエスト（pull request）を教科書のように読めると説明します。ここでいう「教科書のように」は、形式をきれいにするという意味だけではありません。教科書の説明のように、前提を示し、目的を示し、順序を作り、細部へ進むという意味です。

これは、前の章で扱った個別のコード解説にもつながります。エージェントが変更を作ったら、生の差分で止めません。変更を理解するための個人向けの説明文を作り、その中に、背景、直感、説明付きのコード差分を組み込みます。話者は、その結果をIDE（統合開発環境）の画面だけで読むのではなく、印刷して読んでいたと述べています。画面から離れて読み直せる形式にすることも、変更を自分の理解へ取り込む助けになります。

大事な区別：差分は自動的に自己説明しない

「差分には変更された行が全部あるから、説明は不要だ」と考えるのは、この方法へのよくある誤解です。差分は、何が変わったかを示すのに向いています。一方で、リテラシー付きコード差分は、なぜ変わったか、どの順番で理解すればよいか、他の変更とどう関係するかを示します。

この違いは、正しさの確認だけでなく、参加のための理解にも関係します。コードの各行を追うだけでは、変更の全体像をつかむまでに大きな負担がかかります。説明が先にあると、人はコードの細部を読む前に、変更の地図を持てます。その地図を使ってレビューすれば、変更を承認するだけでなく、次の質問やアイデアも出しやすくなります。

話者が示したゼンガーデンの変更について、映像の説明から分かるのは、説明文書が変更の背景とコードを結びつけるという点です。具体的な差分の配置や、実際に変更されたファイルの詳細は、提示された情報だけでは確認できません。ここでは確認できる考え方に絞り、実装の細部を補っていません。