40:PRの差分にレビューアー向け説明を書こう¶
プログラミング迷子: 私が知ってることは先輩なら全部知ってるはず？
先輩T：さっき頼まれたコードレビューなんだけど、ちょっといろいろ情報が足りてなくて、これだとレビューできないよ。
後輩W：え、何が足りないですか？
先輩T：まず、この新機能の仕様はどこにまとまってる？
後輩W：このチケットにまとまってます。途中確認や変更がいろいろあったので、読む必要があるコメントはここと、ここと……あとこの添付ファイルと……。
先輩T：それを読み解いてコードレビューするのは無理だなあ。まず仕様を1箇所見ればわかるようにまとめてください。チケットなら、最終的に決定した仕様をチケット本文に書くといいね。コメントだと流れて行っちゃうから。
後輩W：わかりました。
先輩T：そして、PRの差分それぞれに自分で「その差分が何のためのものなのか、どの仕様のためなのか」を書いてください。レビューアーがその差分を見たときにそれが書いてあれば質問せずに済むので、お互いに質問と回答を書く時間が減らせるよ。そしてもっと重要なのは、実装者自身で説明を書くことで自分の勘違いに気づくチャンスができることだね。
後輩W：なるほどー。
GitHubのPull Request（PR） [1] 機能が登場して以来、コードレビューは格段に行いやすくなりました。 だからといって、PRを作って渡せばわかってもらえる、という訳にはいきません。 レビューアーがレビューしにくい原因は「説明不足」にあります。 説明が不足していると、レビューアーは レビューするべき重要な箇所 に集中できず、些細な問題に気を取られてしまい、重要な問題を見逃してしまいます。 レビューアーから見てわかりやすい依頼にするには、前提になる知識の差を埋める必要があります。
（中略）詳細は書籍 自走プログラマー をご参照ください
ベストプラクティス¶
セルフレビューを行い、レビューアー向けに知識の差を埋めるための説明を書きましょう。
セルフレビューを効果的に行う、6つのプラクティスを紹介します。
実装の根拠を書く
仕様や設計をまとめる
コードを改善する
差分の説明をしてみる
PRの本文（description）に、「PRの目的」「仕様をまとめたページへのリンク」「レビューで確認してほしいこと」を書く
差分コメントを恒久的な情報に移す
- 実装の根拠を書く
コード差分のコメントに、実装の根拠となる「仕様や設計へのリンク」を書くことで、レビュー依頼者がチェックできます。 この作業で、レビュー依頼者は具体的にどの仕様を元に実装したのか、仕様と実装内容が一致しているのか確認できます。 実装コードの中には、効率的なアルゴリズムや、普段使い慣れていないAPI利用などもありますが、レビューアーはその知識がないかもしれません。 レビュー依頼者がそのとき実装して初めて知った情報、初めて使ったAPIについてもコメントに書いておきましょう。 ここで、仕様の理解やAPIの使い方についての認識違いがあれば、レビュー依頼前に気づくことができます。
以下を実践しましょう。
どの仕様のためのコードなのか、仕様へのリンクを書く
仕様を満たしているか確認する
コードを書くときに調べたことがあれば、レビューアーへ伝えるためコメントに書く
（中略）詳細は書籍 自走プログラマー をご参照ください
