きれいなコミットメッセージとは

最近、大きなコードベースを触る機会が増えてきれいなコミットメッセージについて考える事が増えた。きれいなコミットメッセージの定義は様々あると思うが、筆者は下記がきれいなコミットメッセージに必要なことだと考えている。¶

どこに対する変更かが分かる
どんな変更かが分かる
プロジェクト内で統一されている

これに対して、私はcommit_type(module): message という形式でコミットメッセージを記載するのが分かりやすさと手間がちょうど良いのではないかと思っている。¶

順番に説明をしていく。¶

どこに対する変更か

1 つめについては、当たり前のことであると感じるかもしれないが、このうち特に "どこ" の部分がをわかりやすく書くのは難しいのではないかと思っていた。¶

例えば Fix accuracy of retuened value from functionA というコミットメッセージを書いたとしよう。これはどんな変更なのかは分かる、とても普通のコミットメッセージだと思う。¶

ただ、これが大規模なコードベースとなった場合、この functionA がどのモジュール（どこ）なのか、コミットメッセージだけでは判断がつかない。diff を見ればどこのモジュールの変更なのかは一目瞭然であるが、diff を見る手間が発生する(tig などを使えばある程度削減されるが)。¶

気づかないうちにある部分が壊れていて原因となったコミットを探す際、1つ2つのコミットを遡るのであればこれでも良いが、大量のコミットがあるようなプロジェクトの場合、この手間は大きなコストになる。¶

function A in module X というようにモジュールを書くようにするという方法もあるが、少し冗長になってしまうし、英文の最後まで読まなければ分からないという課題もある。¶

そこで (module) という部分を追加することで、どのモジュールかがはっきりと分かる。こうすることで、あるモジュールが壊れていることに気づいたときに (module) で grep すれば、該当コミットが見つけやすい。ここで、module の粒度はチーム内で合意が取れている粒度で記載する。（そうでなければ結局自由に記載しているのと変わらない）¶

このように記載することで、英文を書くのに比べて狙いが分かりやすくなると考える。¶

どんな変更かが分かる

次にどんな変更なのか内容が分かりやすく書くためにはどうするべきかについて述べる。まず、message の部分に、普段どおりのメッセージを記載しておけば、どんな変更なのかはある程度分かる。ただし、英文で記載されているので、どういう変更なのかは英文を読み解かなければ、機能追加なのか、バグフィックスなのかがすぐさま判断つかないことがある。¶

そこで、commit_type を記載するようにする。この commit_type は、例えば下記のようにコミットの作業を大別したもので、チームの中で合意が取れているものにする。¶

feat
chore
fix
docs
perf
refactor
style
test

こうすることで、どういった変更なのかがよりわかりやすくなる。¶

加えて、可能であれば、ここにより長いコミットメッセージを 3 行目以降に記載してもよいと思う。加えて、どの issue に紐付いているのかをコミットメッセージに記載するのも有効なように思う。¶

具体的には下記のように。¶

commit_type(module): short message

long message.

issue: 123456

この long_message や issue を書くかどうかは、手間や、タスクが issue で管理されているかどうかなどに応じて追加してもよいように思う。¶

プロジェクト内で統一されている

先程までのテンプレートに沿うことでプロジェクト内である程度の統一することができる。コミットメッセージが統一されていることで、コミットメッセージを読む側からすると、コミットメッセージごとに読み方の切り替えをする必要性が少なくなり負担が少なくなる。¶

終わりに

このエントリではコミットメッセージをきれいに書くために下記が必要であるという考えを述べた。¶

どこに対する変更かが分かる
どんな変更かが分かる
プロジェクト内で統一されている

これに対して、具体的に私はcommit_type(module): message か¶

commit_type(module): message

long message.

issue: 123456

というコミットメッセージを書くのが良いのではという考えを述べた。¶

この考え方に至ったのは最近で、現在運用しているところなのでまた追加で気づいた事があれば、このエントリをアップデートしたいと思う。¶

もしもよりよいコミットメッセージの書き方、コミットの考え方などがあれば、 @bokken_ まで教えていただけると嬉しい。¶