コミットメッセージの書き方

適切な情報を残そう

risacan

11 min readAug 4, 2017

はじめに

この記事ではGitのコミットメッセージの重要性と良いコミットメッセージの書き方を説明します。いままで良いコミットメッセージについて考えてこなかったかたも一度立ち止まって考えてみてくれると嬉しいです。

対象読者

GitやGitHubを業務で使っている人
「良いコミットメッセージ」をあまり意識しない人

Gitを使ったソフトウェア開発で、なぜコミットメッセージが重要なのか？

ソフトウェア開発において、良いコードとはどんなコードでしょうか？
私は「他人が読みやすく、理解しやすいコード」だと考えています。ソフトウェアにバグは必ず出ます。そのバグを修正する時間を最短にできるような、読みやすい、理解しやすいコードが良いコードだと思います。「”他人が” 読みやすいコード」としているのにも意味があります。それは、私の今までの業務において自分ひとりだけが使うコードは何ひとつなかったからです。今、サービスで動いているコードは、私以外のエンジニアが、過去のある1点において最善を尽くしてかいたコードの積み重ねです。あるいは、すでに見覚えがないけど、私自身が書いたコードかもしれません。

他人あるいは1年後の私自身が、そのコードを理解できるようにしておけば、変更を加えやすくなるでしょう。また、最善を尽くして書いた過去のコードを「変更意図がわからない💩コード」とまるっと削除される悲しみや手間もなくなるでしょう。「コードを書いた本人ではなく他人も理解しやすいかどうか」はそのソフトウェアが将来的に使われるかどうかをも左右する重要事項だと考えられると思います。

コードの5W1H / コミットメッセージの役割

上記の考え方を踏まえて、コミットメッセージをどのように使えばいいか考えます。ここでは、コミットの粒度が適切であることは大前提として話をすすめます。（参考: git commit するまえに考えるべき10のこと | Act as Professional ）

実は、Gitの機能は、情報伝達のポイントといわれる5W1H「いつ（When）、どこで（Where）、だれが（Who）、なにを（What）、なぜ（Why）、どのように（How）」をきちんと表現できるように作られています。
以下コミットメッセージアンチパターン: コメント対応より引用です。

「いつ (When) 」コードに対していつ変更を加えたのかはタイムスタンプを見れば分かる
「どこで (Where) 」コードに対して何を変更を加えたのかはリソース (file/dir) 名で分かる
「誰が (Who) 」コードに対して誰が変更を加えたのかは author を見れば分かる
「何を (What) 」コードに対してどうやって変更を加えたのかは diff を読めば分かる
「なぜ (Why) 」コードに対してなぜ変更を加えたのかはコミットメッセージを読めば分かる
「どうやって (How) 」コードに対してどうやって変更を加えたのかは実装を読めば分かる

このように、Gitにはコードの5W1Hを明確に記録する方法がすべて備わっています！注目したいコミットメッセージの役割は、”なぜ(Why)” コードを変更したのかを表すことです。変更理由をコミットメッセージに詳しく書くことが、他人のコードの理解につながります。また、コミットメッセージを検索できる（Git - 検索 / GitHub Search Commits）ことからもわかるように、索引としての役割も担っています。このコミットメッセージの記述を蔑ろにしてしまうと、コードは理解しづらく、変更箇所は探しづらくなります。コミットメッセージの使い方がソフトウェア開発においていかに重要か伝わったでしょうか。

レビューもしやすく

他人が理解しやすいようにコミットメッセージを書き、コミットすることは、自分自身の成長にも役立ちます。なぜなら、「他人が読みやすく、理解しやすい」コミットは、レビュワーにとってレビューしやすいからです。稚拙なコードを書いたとしても、そのコードを書いた意図が伝われば、アドバイスし易く、リファクタリングもしやすいものです。

コミットメッセージのテンプレート

常に良いコミットをしていきたいので、最低限コードの5W1Hが伝わり、変更理由も忘れず記述でき、コミット粒度も自然に意識できるようなコミットメッセージのルールを自分で決めています。よければ参考にしてください。

テンプレート

ソフトウェアに変更をし、git add -pでコミット粒度を適切にわけたあと、git commitしてエディタを開き、コミットメッセージを書こうとしているとします。その場合以下のように書きます。

1行目: コミットの内容を表す絵文字 + 変更内容を簡潔に英語の命令形で記述
2行目: 空行
3行目以降: なぜ変更したのか詳細な説明を日本語で記述

コミットメッセージの例はこうなります。

:art: Add new images for Summer campaign夏のキャンペーンのため、新規の広告イメージを追加
詳細は #2

GitHub上ではこのように表示されます。

右側の “…” をクリックすると以下のように展開されます。

次の項からなぜこのように書いているか理由を説明します。

2行目に空行を設ける

まず、2行目を空行にする理由です。
コミットメッセージは1行目のコミットサブジェクト（題目）と、コミットサブジェクトとは空行でわけられるメッセージ部分、の2つの部分で構成されています。コミットサブジェクトは、GitHub上ではコミットのタイトルとして、CLI上ではgit log --onelineとした時に表示される重要な一文です。

空行がないと、CLIではこのように表示されてしまいます。

Gitのログは、GitHub上で見る派も、CLIで見る派もいるでしょうから、どちらも見え方に差がないように2行目に空行を入れることにしています。

絵文字について

コミットサブジェクトの最初には、そのコミットの内容を表す１絵文字を入れることにしています。絵文字コミットについてはこちらの記事(Emojiで楽しく綺麗なコミットを手に入れる| Goodpatch Blog)を参考にしてみてください。

私自身はコミット粒度を意識するために絵文字コミットをしています。コミットの内容を表す絵文字が複数になってしまう場合、そのコミットの粒度が正しいのかどうか疑う基準になります。
また、絵文字コミットをするとGitHub上で特定のコミットを探すときの視認性が高まります。

コミットサブジェクトは英語で書く

コミットサブジェクトの文言は英語の命令形で記述しています。これはGitが生成するメッセージに揃えるためです。
（ Merge pull request #1 from add_new_feature、など）
また日本語ではなく英語で記述している理由は、 何をしたか という動詞を一番最初にもってくることで、コミットの検索性を高めるためです。
日本語で記述しようとすると、述語が文章の後ろのほうにくるため、他のコミットサブジェクトと並んだときに 何をしたか という動詞がバラバラの位置にきてしまい、コミットを探しづらくなります。

__Add__ new feature!
__Remove__ hogehoge feature because of the delay of the project
__Remove__ the setting file because of the change of UI
新機能を__追加__！
プロジェクトの遅延に伴うほげほげ機能の__除去__
UIの変更にともなう設定ファイルの__除去__

日本語で 何をしたか という動詞だけを先頭にもってくる方法もあるかとは思いますが、それだと自然言語として読めなくなってしまいます。自然言語として違和感なく読むことができる英語での記述がおすすめです。

３行目以降はなぜ変更したのかを詳しく記述する

３行目以降は “他人” に変更意図が伝わるように、なぜその変更をしたのか丁寧に書きましょう。どれだけ長くなってもいいです。
変更点について話し合ったGitHub IssueやPull Requestがあれば、一緒にのこしておきましょう。GitHubのIssue番号は同じレポジトリ内なら #Issue番号 、他のレポジトリのIssueならユーザー/レポジトリ名#Issue番号 で参照することができます。さらに、Fix#Issue番号 、Close #Issue番号 のように記述することで、該当Issueをクローズすることもできます。（詳細: Closing issues using keywords - User Documentation )

GitHub Issue、 Pulll Request内の特定のコメントにリンクを張りたい場合は、各コメントの日付けからURLを取得できるので、それを使います。Slackの場合は該当コメントの “…”をクリックし、Copy linkを選択することでそのメッセージへのリンクを取得できます。

もちろん、コミットサブジェクトだけでその内容を説明できるのであれば、詳細な説明は不要です。

たまに、「何で動かないのかわからない、最悪」などの個人的なメッセージを見かけますが、想像してみてください。１年後に致命的なバグを解決するための手がかりを求めてコミットメッセージを検索しているときに、その言葉にぶちあたったらどんな気持ちでしょうか。ソフトウェアと開発チームの将来のために、有意義なメッセージ、ポジティブなメッセージを残すようにしましょう。