はじめに
日常的に使用しているPull Request機能でレビューをもらうことは多くあると思います。
もちろん、ほとんどは納得する内容であったり、大いに勉強になるものであると思いますが、コメントの中でモチベーションを落とすものに出会ったこともあると思います。
今回は、そのような自分が出会ってちょっと嫌だなと思ったコメント、また自分が嫌なコメントをしてしまったな、と後で気づいたコメントについても併せて考えていきたいと思います。
必要な情報を口頭で伝えようとする
口頭で伝えましたが、○○の修正をしてください。
○○を修正してください。××については、後で説明します。
わざわざ席に来たり、ビデオチャットのURLを送ってくるなら最初から記載してくれ！！
もちろん、仕様や修正して欲しい内容の説明が必要な時はあると思いますが、「口頭のほうが楽だから」とコミュニケーションコストを相手に押し付けるのも、ほどほどにするのが良いかと思います。
改善案
○○なため、××の修正をお願いします。ここは△△についての補足が必要だと思うので、下記の資料を確認してみてください。補足必要な場合はご連絡いただければと思います。
https://~~~~~
少し冗長な気もしますが、口頭での説明をレビュイーに書き止めさせたり、何も記載しないよりかはいいと思います。なるべくなら対面でのコミュニケーションコストは削減したい派です。
修正が必要なのに確認を促す
ここのコードってこれであってます？確認お願いします。
○○のとき、××のように動きますが、動作正しいですか？
○○では？
実装間違っているなら指摘としてコメントしてくれ！煽ってんのか！！
「すみません、こちらのミスです。」という心理的負担をやりとりとして挟ませる理由はあまりないと思います。レビューもらった時点で自分のミスだな……という自認はあると思うので。
改善案
ここのコードは○○なので、××に修正をお願いします。
具体的にどこが誤った実装になっているか、どう直して欲しいかコメントするだけでいいと思います。
状況だけコメントする
○○が××になる。
単純なメモなのか、それとも直して欲しいのかわからないようなコメントも困ります。
状況だけ記載して、あとはそちらで察してくださいっていうのはレビュアーとしての役割を果たせているのか。そもそも、例のようなコメントはレビュー以前にコミュニケーションの取り方な気もしますが。
改善案
○○した場合、××になってしまうので修正お願いします。
これはレビュー以前の問題ですね。テキストコミュニケーションではありますが、あくまで人とやり取りをしていることを念頭に置きましょう。
長文すぎる
○○についてですが、××は△△なので□□です。なので、○○のところは××にして、△△かどうかで判断して、□□のように修正してください。
短く見えますが、記号のところがもっと長いです。これは私がたまにやってしまうなというコメントで、抜けがないように説明しようとすると、自然と冗長になってしまって、何が言いたいのかわからなくなってしまうという状況ですね。
改善案
○○は××なので、△△に修正してください。不明点あればお声かけください。
もう少し相手を信じて、最低限の説明だけ載せておいて、後はレビュイーの判断にお任せするやり方ですね。
説明が必要であったり、問題があれば連絡が来ると思いますが、声をかけやすい関係を作っておくのも大切だと思います。
まとめ
気にしすぎじゃないか？気を遣わせすぎじゃないか？と思った方もいると思います。
もちろん、あらかじめ関係性が築かれていれば問題として挙げているコメントの仕方でも問題ないと思いますが、じわりじわりと追い込まれて、心理的安全性が確保できなくなっていくことは想像に難しくないと思います。
ただ、目的はコードの品質向上であることが前提ですので、考えすぎて伝えたいことが伝わらないというと本末転倒になってしまいますので、投げっぱなしではありますが、各々の現場・プロジェクトの雰囲気に合わせて調整していただければと思います。