Pull Request に「もやもや」で思いの丈を綴るとコードレビューが捗る

コードレビューはプロダクトの品質向上にとても良い習慣だけど、なかなか効率良くできない。 ただ、時間をかけてもやる価値はあると思うので、何とかならんかなーともやもや考えてます。

コードレビューが面倒に感じるとき

コードレビューに時間がかかるプルリクエストを視るとだいたいこんな感じのことを思う。

• ファイル差分が多いな・・・
• これは何の機能なんだろう？ 細かい仕様は知らないな・・・
• この変更は何がしたいんだ？？？
• プルリクエストの説明が長くて読むのがツライ

めんどくさがりなので、僕はすぐに心が折れます。

規模が大きく、ファイル差分が大きい問題

時と場合により避けられないこともあるので、プルリクエストを小さく分割する努力しつつも諦めが必要だと思います。 すべての差分コードを読むのはツライので、どの辺りを見て欲しいか書いてもらえると大変嬉しいです。

知らない機能のコードレビューが難しい問題

知らない機能に対して、迷っている実装のフォローやリスクがありそうな箇所を見つける様なコードレビューはかなり難しいです。 レビューする側としては、機能の説明があると嬉しいです。

ただ、プルリクエストの説明でベタベタ書くとレビューしてもらいたい観点とごちゃごちゃになって訳が分からなくなるので、 個人的にはIssue に「目的」や「やりたいこと」を書いてリンクするのが良いと思います。 リモートワークでなければ、オフラインでホワイトボードなど使いながら説明すると良いと思います。

目的の分からないPull Request 問題

コードレビューする人を気遣って、規模が大きい機能のプルリクエストを分けたりすると文脈が分からなくなり、かえって混乱を招くことがあります。 関連するIssue やPull Request へのリンクをペタペタ貼っておくと文脈が分かると思います。 あちこち見に行く必要が出るとそれはそれで面倒だったりしますが・・・。 『ファイル差分が大きい問題』と同様に、どの辺りを見て欲しいかを伝える努力はあると良いと思います。

説明が長くて要点が分からない問題

一生懸命説明しようとした結果、「どの辺りを見て欲しいか」という大事なポイントが埋もれて分からなくなる問題です。 頑張ってコードレビューしてコメントすると「説明に書いてあります」と反論される事案も発生します。

仕事の文章の基本に立ち返って、無駄な情報は捨て必要な部分だけ残しましょう。 ついでに、事実と意見（自分が考えて判断したこと）を分けて書いてあるとGood です。

Pull Request で「もやもや」コミュニケーションする

最近はプルリクエストに下記の内容を書くことにしている

• やったこと
  • Issue へのリンクを付けたり、変更点を箇条書き
  • チェックリストにして、WIP Pull Request のTODO リストとして使っても良い
• もやもや
  • レビューで見てもらいたい箇所や不安なことを書く
• テストしたこと
  • 確認したことを箇条書きにする
• スクリーンショット
  • デザインやUI の変更を貼付ける
• 注意事項
  • マージ前後に発生する作業などを注意喚起する

不要な項目は「特になし」など書かずに、見出しごと削除すると良い。 いろいろ検討した結果、無いのであれば明示的に「特になし」としても良いと思います。 また、『やったこと』はファイル差分見て分かるのなら省略しても良いと思います。

「もやもや」を書くコツ

レビューする人に「○○してください」というお願いを書こうとしないこと。 自分が困っている、不安に思っている事を自分主語でつらつら書きなぐるのがコツです。

綺麗に説明しようとして本筋からズレるより、「もやもや」していることをそのまま書いた方がレビューする人に伝わると思います。