よい Git コミットメッセージを書くために気をつけるべきポイント
本日は Git のコミットメッセージについてです。
Git の（広くいうなら VCS の）コミットメッセージは、チームで開発を行う場合、あるいは、個人での開発の場合でも長期にわたって開発を行う場合には「書き方の共通ルール」というものをあらかじめ決めておくと便利です。
このあたりは人それぞれの好みの問題にも関係するので誰もが納得する共通のルールを作ることは難しいのですが、 OSS コミュニティなどで一般に受け入れられているベストプラクティスのようなものはある程度確立されているようです。
私の狭い範囲での観測と学習、経験から思う「いいコミットメッセージを書くために気をつけるべきポイント」をまとめてみました。 興味のある方はご参考にしてみてください。
- 過不足ない長さ
- ほどよい具体性
- 文脈と理由
- 影響範囲と副作用
- 参照
- スタイルの統一
過不足ない長さ
よいコミットメッセージは短すぎず長すぎず、ほどよい分量になっています。
「 Fix the style bug. 」では短すぎますし、 200 文字にも 300 文字にもなるような長い説明は読む人の意思を削いでしまうでしょう。 どう書いても長くしまうような場合は、そもそもそのコミットの粒度が大きすぎないか（含まれる変更の量が多すぎないか）をチェックしましょう。
参考として、英語で書く場合だと 50-72 文字が「ほどよい長さ」とされているようです。
ほどよい具体性
よいコミットメッセージにはほどよい具体性があります。
たとえば、「注文機能の問題を解決。」というメッセージだと具体的にどんな変更が行われているのかわかりません。 逆に「 helper_func_get_order_line_item() の for ループ内の weight の処理を修正。」といったメッセージだと、変更箇所の説明は具体的でよくわかりますが、それがどんな問題を解決するためのものなのかわかりません。
適度の具体性を持たせてわかりやすく書くことが大切です。
文脈と理由
よいコミットメッセージは、その変更が必要な文脈と理由を説明してくれます。
再び上の「注文機能の問題を解決。」の例を見てみます。 このメッセージは上述のとおり具体性の欠如という点で問題がありますが、具体性の欠如の問題というのはコミットの中身を読みさえすれば解決することができます。 一方で、そのコミットが必要となったおおもとの理由――いわゆる「 WHY 」の問題については、コミットの中身を読んでもわかりません（推測することはできますが）。
ですので、コミットの文脈や理由といったメタ情報をメッセージ内に書くのがよいでしょう。 一般には、「詳しい説明はイシュー管理ツールの方に書き、コミットメッセージにはイシュー番号だけを書く」ことが多いようです。
「問題の解決方法がただ 1 つしか存在しない」という場合はむしろ稀なので、「数ある解決方法の中からなぜ他でもないこのアプローチを選んだのか」という理由が添えられていた方がいいでしょう。
影響範囲と副作用
よいコミットメッセージは、コミットの変更に重要な副作用が含まれる場合にはそれを説明します。
このようなケースは比較的稀ですが、特定の問題を解決するために別の問題をやむなく引き起こしてしまう場合は、そのことについて適切に説明すべきです。
参照
よいコミットメッセージは、必要な外部リソースに対する参照を持っています。
イシュー管理ツールを使っているような場合や重要な参考情報が存在するような場合には、それらの URL 等に言及しておくとよいでしょう。 コミットメッセージは通常テキスト情報だけになるので、概念的な説明のための画像などが必要な場合にはイシュー管理ツールを使うとよいでしょう。
一般には、イシュー管理（チケット駆動開発）を基本とし、コミットメッセージにはイシュー番号を必ず含めるようにしているチームが多いようです。
スタイルの統一
よいコミットメッセージは、標準的なスタイルを持っています。
これは単体のコミットメッセージではなく、一連の流れとしてのコミットログを見るときの利便性を考慮したときのポイントです。
たとえばメッセージを英語で書く場合、文章の先頭の動詞を命令形（例: Add ）で書くのか三人称単数形（例: Adds ）で書くのか、はたまた過去形（例: Added ）で書くのかというのは議論の分かれるところですが、ひとつのプロジェクトの中では共通のスタイルにするのがよいでしょう。
これは一覧したときのメッセージの読みやすさや検索しやすさの点で大きな効果を発揮します。
...
以上です。
コミットメッセージは特にルールがないとついなぁなぁで適当に書いてしまいがちですが、コミュニケーションの改善や開発効率の向上のためには基本原則とスタイルを明確に決めることが有用です。
・・・ダメなコミットメッセージというのは「あ、これダメだ！」と一目でわかりますが（笑）、じゃあ逆に「いいコミットメッセージのコツは？」と問われるとなかなかうまく答えることができないので、今回試しにまとめてみました。 ご参考に。
他にも気をつけるべきポイントをご存知の方がいらっしゃったらぜひ教えてください。