背景・動機
ソースコードレビューをする（受ける）際に、コメントに困る（困らせてしまう）事があります。
自分なりに原因を考え、レビューで気をつけていることをまとめることで、他の人の参考になればと思い投稿します。
レビューするときに気をつけていること
- 具体的に書く
- 理由を書く
- 代案を提示する
1. 具体的に書く
// Bad
もっと良くできるはずなので、頑張りましょう。
// Good
if-elseの階層が深くなっているので、早期returnしましょう。
具体的でないコメントはレビューイを混乱させてしまいます。
そういった意図がなくても批判と受け止められることもあり、レビューに対する意欲の低下にもつながります。
2. 理由を書く
// Bad
変数 user_data の定義を L199 に移動しましょう。
// Good
変数 user_data は利用する直前の L199 で定義しましょう。変数のスコープが広くなると、バグが混入する原因となってしまう可能性があります。
レビュアーは完璧ではないので、間違った指摘をすることもあります。
上記の例で、もしかしたら他の行で user_data が利用されているかもしれません。
コメントに理由が書かれていると、レビューイは指摘の意図を汲んで、変数のスコープをなるべく狭くするよう修正するでしょう。
さらに、次から同様の指摘を受けないよう、学習し改善してくれるかもしれません。
3. 代案を提示する
// Bad
User.checkStatus というメソッド名では、何をチェックしているのか分かりません。
// Good
User.checkStatus というメソッド名では、何をチェックしているのか分からないので User.isActiveState というメソッド名にしましょう。
代案が提示されていないと、レビューイはどう修正すれば分からずコメントを返すか、間違った理解をして修正をしてしまい、コメントのやり取りの回数が増えます。
スケジュールが差し迫っている場合（時間が余っている事などないと思いますが）は、レビュアー、レビューイ共に負担となってしまいます。
上記の例で、レビューイは User.checkUserStatus と修正するかもしれません。
実は checkStatus は Active 以外も判定している可能性もあります。
コメントに代案が提示されていると、レビューイは意図を汲んで説明的なメソッド名を付けるでしょう。
レビューを受けるときに気をつけていること
- 感謝する
- まず最初に自分がレビューする
- 何をレビューしてもらいたいのか書く
1. 感謝する
レビューしてくれたことに感謝します。
例えレビュアーから痛烈なコメントを受けたとしても、時間を割いて自分の書いたコードを読んでくれたことに感謝しましょう。
2. まず最初に自分がレビューする
自分が書いたコードの最初のレビュアーになりましょう。
一旦冷静になって、自分の書いたコードを読み返してみると、良くない部分が見つかることもあります。
3. 何をレビューしてもらいたいのか書く
どういった部分に対して重点的にレビューしてもらいたいのか、自分の意見で良いので Pull Request に記載します。
レビュアーが忙しく時間がない場合（多分そういった人がレビュアーである事が多いと思います）重要な情報源となります。
終わりに
過去レビューにおいて、相手への配慮を欠き失敗したことがあります。
本記事は自分の経験に基づき作成しているものですので、万人に共通するものではないかもしれませんが、レビューで建設的なコミュニケーションがされると、非常に気持ち良いですので、ご参考いただければと思います。