コミットとレビュワーに愛と感謝を
「このコードの修正内容はなんですか？」
つい先日、メンターをしてくださっている先輩エンジニアが自分のPRをレビューしてくれた時にこんな感じで聞いてこられた。聞かれたからには説明が必要なので説明すると、「そういった理由があるのなら、コミットメッセージに書いてほしい！」と言われた。。。。至極ごもっとも。本当にそのとおりだと思い反省した（汗）。
これを機にいままでの自分のコミットを見返してみると結構恥ずかしいものが多かった。コミットの粒度も気分で大きかったり、小さかったりするから、１コミットがどこまでで修正した内容なのかわかりづらい。しかもコミットメッセージも「〇〇を修正した」とか「〇〇の指摘を対応した」と理由も何も書いてないので、レビュワーは辛みを感じてしまうのは必至。これでは良くないなと思い、最近になって意識し始めた事を書いてみる。
コミットとレビュワーに愛と感謝を
今回の一件で「コミットメッセージが多少長くなってしまっても、修正の経緯が理解しづらくなるよりはいいかな」と思うようになり、レビュワーを思いやるコミットを意識するようになった。もっとレビュワーの視点に立った粒度と説明をコミットに込めるのが、レビューのしやすさを向上し、より良いマサカリをもらうきっかけになるはず。もっと言えばレビューもしやすくなってチームの開発サイクルが少しだけ向上するかもしれない。
具体的に以下の３点を意識している
git commit --one-lineの１行は「何故変更したのか？」という理由をつけて、出来るだけ簡潔かつ具体的な修正内容を書く（例：N + 1問題が発生しているため、includeを追加する）- 1.で説明しきれない内容や参考にしたURLなどは、
git commitの３行目以降の補足？に記述する。 - コミットの粒度は余り大きくなり過ぎない。
1について
開発者によっては「コミットメッセージ（題目）は最低限に書くべき。語るならコードで語れ」と仰る方もいる（現に前職の先輩はそうだった）。しかし、これが結構難しい。限られた文章量で上手く説明しきれないこともある。そして中途半端な説明を書いて、レビュワーに変更の意図が伝わらず、都度説明をする時間を取るくらいだったら、説明を詳しく書いた方がその分のやり取りも節約できると思う。 githubにPRを出すと１行目のコミットメッセージが出るので、多くのエンジニアがこのメッセージを参考にレビューをすると思う。ここに「理由 + 具体的な修正内容」を入れれば、修正の意図を理解しやすくなってもらえるはず。意図を理解してもらえれば、レビューもしやすくなると思う。
2について
１で説明する文字数も限られているが、どうしても説明したい内容や参考にしたURLがあるので補足したいと思ったら、１行目のあとに２行目を空白行にし、３行目以降に書くことにしている。 ただ注意したほうがいいと思うのは、全てのコミット毎に３行目以降の補足を付ける必要はないし、多用するべきでは無いかなと思う。開発者によってはこの補足説明をあまり見る習慣がない人もいるっぽい（個人の肌感だけど）し、毎コミットに長い説明があるとレビューも疲れてしまう。なので、あくまで補足や説明しきれない内容を詳しく書くときだけに利用する位に留めている（ここには修正の意図や説明を書く以外にも、最近は「あんまり自信がないので、もっと良い書き方があったら教えて貰いたいです」と助け舟を書いてみるのも良いかもしれない）。
3について
コミットの粒度は出来るだけ大きくなり過ぎない。これが結構難しい。個人的に。
１修正１コミットというのは念頭においているのだけど、この1修正の区切りが本当に人によって違う。極端な例だけど、何かの一覧から文字列検索できる機能を作るとして、１修正１コミットを「一覧から文字列検索できるようにする」と１機能の開発をまるっと１コミットにする人もいれば、「文字列検索のための検索窓を設置」→「controllerに検索機能を追加」→「バリデーションを追加」→「検索後のメッセージを追加」・・・・と細かく区切る人もいる。
自分はここで言う後者をしばらく目指して行こうかなと思っている。出来るだけコミットを小さく区切ればレビュー時に「なるほどこういう経緯で修正したのか」と気づいてくれて、良いマサカリを投げてくれること多くなると思う。
コミットは小さく区切れば、1の説明もしやすくなると思うし、説明量も少くなることが多くなるので、あまり２の補足説明を多用しなくなるはず。
会社によってはコミットに絵文字を入れたりする工夫がなされていて、やり方はいくらでもあると思うけれど、今は最低限上記の３つを意識しながらやっていこうかなという所存。
