私がコードレビューの際に気をつけているコメントの書き方

こんにちは、BASE株式会社 ランニング部部長の元木です。
日々、社員に運動不足解消を促す傍ら、Owners Marketingというチームでバックエンドエンジニアをしています。

さて、弊社ではソースコードを変更した際に必ずメンバー間でコードレビューを行ない、OKが出たコードだけをデプロイすることになっております。

今ではほとんどの開発現場でコードレビューを取り入れていると思いますが、読者の中には

「レビューのコメントって、どう書いたらいいのか分からない」
「こんな事を言って嫌な顔をされたり、喧嘩にならないか心配」

などと、苦手意識を持っている人もいるのではないでしょうか？

そこで、今回は私がコードレビューの際に気をつけているコメントの書き方をご紹介したいと思います。

気を付けているポイントとレビューコメントの書き方の例

私は、レビューで指摘事項をコメントする際のポイントは
「いかに分かりやすく、納得感のあるコメントを書けるか」
だと考えております。

そのために、コメントは以下の順に書くようにしています。

1. どのように修正してほしいか
2. なぜ、そのように修正してほしいのか
3. エビデンス

それでは、以下仮のPHPコードを例に順を追ってご説明します。

<?php
/**
 * 引数 $phone_number が電話番号であることをチェックする。
 * ただし、厳密なチェックはせず、'-'を除いた後の桁数と数字だけの文字列であることのみチェックする。
 *
 * @param string $phone_number 電話番号
 * @return bool 引数 $phone_number が電話番号ならば true。
 */
function is_phone_number(string $phone_number): bool
{
    $phone_number = str_replace('-', '', $phone_number);

    $length = strlen($phone_number);
    if ($length < 10 || $length > 11) {
        return false;
    }
    
    return is_numeric($phone_number);
}

このコードは実装者の意図通りに動くでしょうか？ 結論を言うと、このコードにはバグがあります。それをコメントで指摘してあげましょう。

まずは悪い例から。

こんなコメントをする人はまずいないと思いますが、下手をすれば喧嘩になるかもしれません。

では、次はどうでしょうか？

間違ったことは書いていません。

なぜか、を同時に書くと親切かなとおもいます。

分かりやすくなりました。

エビデンスを示すのは、親切心のためだけではありません。勘違いなどにより、間違った指摘をしてしまうのを防ぐ目的もあります。

しかし、これを読んだレビュイーは
「じゃあ、どうすればいいの？」
と悩むかもしれません。
特にレビュイーが新人プログラマーだった場合は、そうなりやすいです。

そこで、「どのように修正してほしいか」も追記します。

これならレビュイーも悩む必要がなくなりますね。

最後に、修正方法を先頭に移動します。

最初の一文だけ読めば結論がわかるようになりました。

日本語の文章としてはちょっと違和感があるかもしれませんが、こちらの方が読み手に優しい文章だと思います。
それに、熟練のプログラマーなら結論だけで
「あ、そうか」
と気づいてくれるかもしれません。

もちろん、すべてのコメントをこのように書けるとは限りません。
問題があることは分かったけど修正方法が思いつかないこともありますし、エビデンスを示すのが難しい指摘事項などもあるからです。

そういった場合は無理せず、書けることだけをコメントするとよいと思いました。
他のレビュアーが補足してくれるかもしれませんし、大抵の場合、レビュイーはコメントをもらえるだけで十分にありがたいと思ってくれるはずです。

コードレビューはみんなの資産

コードレビューは、ぶっきらぼうなコメントですと殺伐としたり、そうなるのが嫌で億劫になりがちです。
HRTのマインドセットをお互いに持ち、コメントの書き方を工夫することで、レビューしやすい/されやすい文化が育まれ、良いコードと良いチームへ繋がっていくと思います。