プルリクのコメントは大事

先日投稿した 大きいプルリクはつらい というエントリで、レビュー側の負担を少なする術を書きましたが、その続編を書きます。これも自戒の意を込めています。

コメントを残す

PR を見ればコードの diff が分かるので、どんな変更を加えられたのか、その変更によりサービスの挙動がどのように変更されたのかが分かります。

ですが、その内容によっては、なぜその変更が必要なのか、その変更により何が幸せになるのか分かりづらいことがあります。一般的な機能の追加等であれば、そりゃ便利になるよねと理解できるかもしれませんが、そうでないことがあることをを意識する必要があります。

また、コードを書いたものにしか分かりづらい情報、例えば、マジックナンバを使用した際には、何故マジックナンバで良いのかといった情報もコメントとして残すべきです。
PR での変更点以外のコードをいろいろ探ったり、PR を出した人に聞けば分かることかもしれませんが、コードの調査には時間がかかりますし、聞く場合も遠距離で開発している場合にはなかなか難しいこともあります。
さらに、分かりづらい PR の場合は、レビュー側も「分かりづらいから時間のあるときにレビューしよう」というように考えてしまうと思うので、開発自体のスピードが低下してしまうかもしれません。

そのため、あらかじめコメントを記述しておくようにしておくべきです。

コミットメッセージには意味を持たせる

コミットメッセージは、変更点の記述にしないようにすべきです。

コミットの diff を見ればどんな変更が加えられたのかは分かるので、XXXの変更 というメッセージは意味のない情報になってしまいます。
こちらも、コメント同様に、なぜその変更をしたのかや、その変更でどうなるのかを記述するようにすべきです。

最近これらができていないことがあったりしたので書きました。
こういったことを意識して、円滑に開発を進めたい！！