コードレビュー時のコメントの意図を明確にする

コードレビューあるあるなんですけど、レビューする時に「これってなんでこうしてるんですか？」みたいなピュアなコメントを書いてしまうと、その意図がレビュイーに伝わらなくて、「詰められてる」「コードに疑念を持たれている」「修正依頼をされている」「純粋に質問されている」という解釈のブレを生んでしまって物事が円滑にいかないみたいなことは発生します。

コメントする側からするとただ単に質問しているだけなのにどうして・・・と思いがちなのですが、コードレビューに慣れていない人はこういう重要度や意図がはっきりしないコメントをたくさん書いてレビュイーを困惑させがちというのはあるんじゃないでしょうか。

重要度や意図がはっきりしないコメントを書くのが常になってしまうと、GitHubでPRを出してレビューをしてもらってマージするという開発者が何度も何度も回していくワークフローに滞りが発生してしまう、もしくはそれどころかレビューコメントでレスバが始まって空気が悪くなったりするのでそういったことは避けたいですよね。

解決策としては、例えば純粋に質問したい場合には「これってなんでこうしてるんですか？　僕が単純にわかっていないので教えてください」みたいな感じで一言付け加えるだけで解決する話なんですが、とはいえ質問する時に毎回こういうフォロー文を書くのもどうかと思うし、メンバー個々人の日本語の運用能力に依存してしまうという問題はあります。

そこでおすすめしたいのは、コメントの意図をタグとしてあらかじめ明確に書いておくという方法です。修正を依頼したいのであれば[修正依頼]、質問なのであれば[質問]、参考情報であれば[参考]、変更の提案であれば[提案]というタグをコメントの頭に書いておくという方法です。単純なやり方ですが、意図をあらかじめ明確にできるので、コメントの解釈がブレるということを減らせます(ここでは単純なやり方を書いていますが、しっかりと定義されたレビュー時コメントの規約としてはConventional Commentsというのもあります)。

あとは無視されがちな点ですが、レビュー時のコメントで修正依頼を書くとしてもマージをブロックする問題でなければ、PRの滞留を防ぐために「別PRで修正可です」「別PRで修正お願いします」と一言添えておくのも開発ワークフローを円滑に回すのに重要なことです。

コードレビューを何も考え無しに運用していくと、開発ワークフローがいまいちうまく回らない結果になることもあるので、どうやって運用していくのかについては知見を集めつつチーム内でコードレビューのやり方や規約を共有していくといいんじゃないかなと思います。以上コードレビュー時のコメントについての雑感でした。