LoginSignup
131
125

より良い Git コミットメッセージを書こう

Last updated at Posted at 2024-04-26

より良いコミットメッセージを残すことは 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 を使う理由が明確になっています。

まとめ

コミットメッセージはコードを保守する上で重要なヒントになるものです。そのコミットが作られた理由が明確になるように書きましょう。

半年後の自分や、他人が見ても理解できるコメントを書くよう心がけましょう。

131
125
1

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
131
125