良いコミットの積み方

人間は書くことよりも読むことのほうが多い。
つまり、「読みやすい > 書きやすい」ということ。

コミットログはレビュー時に参照されます。
つまり、良いコミットの積み方をすればレビュー時に読みやすくなり、チームの生産性が上がります。
逆に、悪いコミットの積み方をすればレビュー時に読みづらく、時間がかかったり、レビューの精度が下がるでしょう。

コミットの粒度

作業単位ではなく機能単位でコミットをする

悪い方法❌

  • Controllerの処理を書いた
  • Modelの処理を書いた
  • Serviceの処理を書いた
  • テストを書いた

良い方法⭕️

  • ユーザー情報を返すAPIを書いた
  • ユーザー情報を返すAPIに認可を追加した
  • ユーザー情報を返すAPIに回数制限を追加した

つまり、ひとつひとつのコミットの中にE2Eな変更(もちろんテストも含まれる)が入っているということです。

レビューでの指摘事項の修正はやリファクタリングなどは機能単位でない場合もあるので一概には言えませんが、基本方針としては機能単位で書くと読みやすくなります。

なぜ?

作業単位で書くと、そのコミット内で見るべき内容が固定されません。
例えば上の例の場合、Modelの処理を書くことによって、Controllerの処理が多少なりとも変化します。

レビュアーの立場から見ると、「このコードが足りてないな」と思ってコメントし、次のコミットに移るとコメントの内容の変更が書かれていたりするわけです。
そうすると、レビュアーはControllerの処理がいつFixされる(レビューコメントを書ける)状態になるか把握できません。

一方で機能単位でコミットをすると、そのコミットがその機能を満たしているかをレビューすることができます。

1機能ずつコミットする

悪い方法❌

  • レビューでの指摘事項をまとめて修正した

良い方法⭕️

なぜ?

単純に、どの差分がどの項目に影響しているかわかりやすくするためです。

コミットメッセージ

prefixをつける

チームでprefixをつける運用をしている場合はprefixを付けましょう。
prefixを運用していないチームではオプションです。

悪い方法❌

  • 認証処理が抜けていたので修正

良い方法⭕️

  • fix: 認証処理が抜けていたので修正

なぜ?

prefixをつけることにより、どういった分野の変更を行いたいかを、コミットメッセージやコードを読む前に把握することができます。

変更した内容を書く

悪い方法❌

  • fix: Fix FeedBack

良い方法⭕️

  • fix: 変数名をわかりやすいものに修正

なぜ?

何をしたのかわからないと、コードから「こういう意図で変更したのかな?」と推測することしかできず、レビューの精度が下がるためです。

その他

Commit Suggestion を使おう(GitHubを使用している場合)

修正案を提案されたときに、「これはこの人の功績なのに自分の名前でコミットしていいんだろうか・・・」とか思いますよね。
Commit Suggestion を使用するとコミットのauthorに提案した人も含まれるので、そういった心配もなくまります。