より良いコミットメッセージを残すことは Git を使った開発をする上で重要なことです。優れたコミットメッセージは、それを読んだ人がコードを理解するのに大いに役立ちます。
では、どのようなメッセージが良いもので、どのようなメッセージが悪いものなのでしょうか？ それについて掘り下げていきたいと思います。
基本的な Git Commit Message の書き方
詳しいところは、以下の3サイトを参照してください。特に「How to Write a Git Commit Message」には基本がすべて書かれています。
How to Write a Git Commit Message
https://cbea.ms/git-commit/
Gitのコミットメッセージをうまく作成する7つのルール （「How to Write a Git Commit Message」の和訳記事）
https://meetup-jp.toast.com/839
[転載] gitにおけるコミットログ/メッセージ例文集100
https://gist.github.com/mono0926/e6ffd032c384ee4c1cef5a2aa4f778d7
まず、英語の Commit Message については、日本語でも適用できる点、そうでない点があります。例えば「大文字で始める」というルールは日本語には適用できませんが、「本文はどのようによりも何を、なぜに合わせて作成する」というルールは日本語でも有用です。
まずは英語のコミットメッセージの書き方を知っておいて、日本語でも有用なところを取り入れていきましょう(もちろん、英語の Commit Message を書く場合はそのような心配はありません)。
コミットメッセージの実例
では次に、実際にコミットメッセージの例を見てみましょう。
「レビュー対応」「指摘修正」
レビュー対応
指摘箇所を修正
一見して無難なコメントに見えますが、これらは実のところ何の情報も得られないコメントです。一体どのようなレビュー指摘があったのでしょうか？ それが分からないので、コードの修正差分を見ても妥当性が分かりません。後から見返して非常に困ってしまうコメントなのです。
基本的に「レビュー指摘があった」ことはコミットメッセージに残す必要はありません。それよりも、指摘の内容をコメントに残す方が有用です。
例外発生時にトランザクションをrollbackする
watchで値を更新するのを止めてcomputedを使う
このように、修正の理由が明確になるコメントを残しましょう。
「●●を修正する」
ユーザー登録APIを修正する
SQLを修正する
これも良くないパターンです。
何を修正したのか(What)、どのような修正を行ったのか(How)は、修正差分を見れば分かります。コミットメッセージとしては有用ではありません。
大事なのはなぜ修正したのか(Why)です。同じ修正に対しても、例えば以下の書き方であれば分かりやすくなります。
ユーザー登録APIの入力チェックを強化する
SQLインジェクションを修正する
これであれば、ユーザー登録APIやSQLを修正する理由が明確ですね。
「●●を追加する」
ユーザー登録APIを追加する
SQL を追加する
これは、先ほどの例の「修正する」を「追加する」に書き換えたものですが、コメントの良し悪しについては評価が変わります。
「ユーザー登録APIを追加する」は、良いコメントです。新しい機能を追加することは、それ自体が理由になり得ます。ユーザーを登録する機能が必要だったからこそ、登録APIを追加したのでしょう。
一方で「SQLを追加する」は、悪いコメントです。どのようなSQLが追加されたのか分かりませんし、その理由も伺い知れません。
リファクタリング
コードフォーマットを修正する
count() -> getCount()
これらも良いコメントです。ロジックに変化がなく、コードを整形されていたり、メソッド名が修正されていることが予想できます。
後者のような「aaa -> bbb」が許容されるのは意外に思うかも知れませんが、リネームの書き方として定着しているものであり、問題ありません。丁寧に書くのであれば、以下のように書いても良いでしょう。
Rename count() -> getCount()
なお、「->」はあくまでリネームやタイポの修正を意図するものなので、それ以外で使わないようにしましょう。以下は悪い例です。
Redis keys -> scan
これは以下のように書き換えるべきです。
Redis の負荷を軽減するため keys の代わりに scan を使う
書き換え前と比べ、 scan を使う理由が明確になっています。
まとめ
コミットメッセージはコードを保守する上で重要なヒントになるものです。そのコミットが作られた理由が明確になるように書きましょう。
半年後の自分や、他人が見ても理解できるコメントを書くよう心がけましょう。