コミットメッセージのいい感じな書き方

以前はコミットメッセージの書き方に悩んでたんですが、色々参考にしてだいぶマシになったので僕が書いている書き方を紹介しようと思います。

大まかなフォーマット

大体のフォーマットはこんな感じです。

[操作内容] [影響を受ける範囲] (to | for) [変更をした理由] (あとは詳細度を高める説明)

いくつか例を書いてみます。

(2FA を設定していないユーザーのセッション時間を短くしています)

Update LoginSession to shorten login sessions for users not setting up 2FA

(不要な DB アクセスのログを削除しています)

Remove DB access logging for unused logs

(ユーザーの更新項目が空の場合を想定したテストを追加しています)

Add tests of UserUpdate to handle empty input of fields

大体こんな感じになります。

操作内容に書くのはコミットがどのようなことを行うのかを書きます。大体は Add,Update,Delete,Remove などが多いです。
Delete と Remove の使い分けとしては、Remove はほぼ自明的に不要なものの削除に対してですが、Delete は削除を強調するのに使っています。
後述するコミットメッセージを書く目的にも関わるのですが、後からコミットログを見た時に注意して見たいところは Delete を使うという感じです。

影響を受ける範囲はコミットの対象を書きます。変更を加えたファイル名や、機能名、コンポーネント名、あるいは技術要素(Cookie など)を書きます。
個人的に気をつけていることとしては、プロジェクトや社内で使われている開発用語を使うことと、変更したもの自体よりも影響を受けるところを書くことです。
例えば、上記であげた例でいうと

Update redis conf to change expire time

よりも

Update LoginSession to shorten login sessions for users not setting up 2FA

というふうに、変更を加えた結果を書いた方がトラブルシューティングを行うときにすぐに原因を見つけることができます。

変更した理由はコミットを行った理由を書きます。文章の文脈としては Why ですが、大体はコミットの What を書く感じになります。
個人的によく使うのをいくつか書いてみます。

to handle~ (例外処理や特定ケースの入力についての処理を足すとき)
to adjust~ (フロントのスタイル調整をした時など)
to prevent~ (特定の事象を防ぐためとか。to prevent the submit button from being clicked repeatedly で送信ボタンを連続してクリックするのを防ぐ)
to fix~ (概念が広いのであまり使いたくないのですが、いい単語を思いつかない時に使ってます)
to implement~ (API やインターフェイスをがっつり実装した時とか)

いくつか自分なりのパターンを用意しておくと、コミットメッセージを書くときに悩まなくてよくなります。

このフォーマットのメリット

このフォーマットにしてからいいと思ったことを書きます。

ログを見て自分が何をやったのかがわかりやすくなった

チーム内で進捗確認を行うことがあるのですが、自分が行ったコミットの内容を拾って報告しています。
以前はあまりにも適当なコミットメッセージを作ってたので(fix errors など)、コミットの diff まで確認しないと何を行ったかがわかりませんでした。
現在では、コミットメッセージから何を行ったかがわかりますし、本来であればこれが望ましい姿なんだなと思いました。

トラブルシューティングの時に原因追及がしやすい

リリース後にサービスなどでバグや不具合が発生すると、原因を見つけるためにコミットログを見ていくかと思います。
このフォーマットでは、コミットの前半に影響範囲が書いてあるので、不具合とコミットの関連性が見えやすくなっています。

コミットの粒度が適切になる

このフォーマットで影響範囲や変更理由を明記することで、複数の内容が含まれたコミットメッセージが書きにくくなってます。
and などの接続詞をできるだけ使わないなどのルールを取り入れると、自然とコミットの粒度が適切になると感じています。

コミットメッセージが書きやすくなる

意外かもしれないですが、適当に書いてた時よりもコミットメッセージを書く時間が減ったように思います。
以前は変更内容を見て、メッセージをどうしようかうんうん悩んでました。
フォーマットを作ってしばらくすると、内容がほぼパターン化されて、自然とメッセージが頭に浮かんで後は書き込むだけみたいな感じになります。

コミットメッセージを書く目的

今更ですが、コミットメッセージを書く目的について考えてみます。
元も子もない答えですが、これはサービスやプロジェクトの状況などによって全然違うと思います。

私の場合は、ある程度のユーザ数を有するサービスを複数人で開発しているので、他の開発者から見てわかりやすかったり、やったことを一目でわかることを意識して書いています。コミット粒度についても、revert や cherry-pick、pull-request がやりやすくなるように意識しています。

これが例えば新サービスを新しく作る場合だと、ある程度大きなコミット粒度になると思いますし、コミットログを見ることないからメッセージも適当にしているということもあると思います。

もしプロジェクトでフォーマットが定められているなら、それに合わせることをお勧めします。
私もプロジェクトのSemantic Commit Messageに従って、実際のコミットは以下のような感じになってます。

feat: Update LoginSession to shorten login sessions for users not setting up 2FA #114

なので、私の書き方も参考程度にして、個々の状況に合わせて取り入れるのがいいと思います。