初心者から一歩抜け出すためのGitの業 〜 コミットコメント

多分、Gitを使い始めて詰まる（というか悩む）ところの大多数が、「コミットコメント」だと思う。
これについては色々な人が色々なことを書いていて、結構どれも正しいので、それらを参考にしてもらうのが良いと思う。

じゃあ俺はこれから何を書くのか、というと、
こういう風にコメントするとチーム開発が捗るよ
というのを書こうと思う。
俺自身も出来てないことが多いので、自戒を込めて書くことにした。

※注意！

この記事は「ウチのチームで俺はこういうのを意識してコミットコメントを書いている」というものであって、
万人にドンピシャリと来るものではないというのを予めお伝えしておく。

コミットが何を変えるのかを明確にする

たとえばこんなコミットコメントがあったとする。

Fix some bugs

アウト。ダンゴで試合終了。

"Fix some bugs"、直訳すると「いくつかバグ直したぜ！」である。どこの、どんなバグを、何個直したのかが全くもって不明瞭で、何を言いたいのか伝わらない。
ひとつのコミットで複数の変更をするというのも、個人的には納得がいかないが、それは以下のように書くことで、百歩譲って許す。

fix some bugs

- Typo
- This feature is already gone.

じゃぁ、どうなってるのが（俺の）理想なのか。それは、
1コミットにつき1つのバグを直す
である。上の例で言うなら、

Typo

と、

This feature is already gone

は、別物としてコミットする。そうすることで、そのコミットがプロダクトに対してどのように作用するのかが、タイトル1行読むだけで理解できるようになる。コミットコメントにストーリーが生まれるのだ。大変わかりやすいではないか。
あ、ちなみに個人的には、

Fix failing specs

はアリ。なんでかというと、「死んでるspecを直した」っていうのはコード自体には影響しないし、特に価値を生み出してるわけでもないし、あと他に書きようがないから。

チームで言葉の意味を育てる

割と啓蒙活動的なところがあるが、結構そういうもんだと思う。

たとえば、某弊社のプロダクトには時々、

Oooops

とか、

indent

とかっていう、一言で済ましちゃうコミットが発生したりする。
「いやいや全然内容わかんないじゃんなんだよこれ」
と思う人が大半だろう。だがこれらのコミット、うちのチームでは余裕で意味が通じる。
なぜかというと、「時々発生する＝内容が推察しやすい」からだ。
indentって言われたら、「Hamlのインデント間違ってたんだろうなぁ」と思うし、Oooopsって言われたら、「まぁ多分置換し忘れたんだろう」と、こんな感じだ。
究極的なことを言ってしまうと、俺はコミットコメントはそのリポジトリに関わる人に意味が通じるならOKと思っている。ので、上記したコメントは意味が通じているのでOKだ。
（もちろんそれがバグになる可能性も否定出来ないので、結局全コミット見返している）
言ってしまえば、定型文だ。「拝啓」とか「敬具」と同じレベルだ。

そして、この項についてはこれだけは理解してほしい。

オープンソースにコミットするなら、そこの流儀を守って、コミットコメントもそこの例に習うべき。

自分にしか通じないコミットコメントは、混乱しか生まない。

FIXMEを潰した！と書く

某弊社のプロダクトなんかのログでよく見られる光景に、「FIXMEを潰しといたよ」というものがある。
デザイナーと協業する上で、作ったデザインの中に、「こんな感じで動作するようにロジックをいれこんでください」という説明が、FIXMEを添えて埋め込まれているのだ。
なので、FIXMEを潰したぜ、という意味を込めて、FIXYOUと付けてコミットしている。例えば、

show.html.haml

-#FIXME 名前をデータベースから出すようにしてください
= '馬場達郎'

というコードがあったとして（某弊社のプロダクトで実際にこんなんがあった）、これを修正したコミットは、

FIXYOU; Show full name of the user from database

と、こんな感じになる。こうすればFIXMEと付けた人間は、「あ、直ったんだアレ」というのが一目で分かるし、周りの人間も「バグ修正的な？」というふうに、内容の想像が付きやすい。

コミットコメントは動詞（一人称の現在形）から始める

ここまでの例で、

Fixed a bug

というような、「過去形」が1つも無いという事実に気づいた人はいるだろうか。
実は某社の某プロダクトを開発している某チームは、コミットコメントでほとんど過去形を使わない（もちろん例外はある）。
なぜかというと、コミットする瞬間を起点にして、「今」「そのコミットが」「リポジトリに対してどんな変化を与えるのか」を記述しているからだ。
コミットコメントを以下のようにエア置換すると分かりやすい。

(This commit) Fixes a bug

理解しやすくなったはずだ。あくまでリポジトリにどんな変更を入れるか、なので、主体はコミットであるべきで、ここであえて「俺が直したんだぜ」とかそういうのは必要ない。そもそも誰がコミットしたのかなんてコミットのAuthorを見れば分かる。

emojiを上手く使う

例えば、「昔使ってたメソッドだけどもう使われてなくて、でも消すのを忘れてしまっていた」みたいなメソッドを消しました、というのはよくある話だと思う。
そんな時に便利なのが、 :put_litter_in_its_place: である。
といったふうに、いろいろなシーンでemojiを有効活用することで、ちょっと肩の力を抜いた感じのコミュニケーションを生むことが出来るのはオススメだ。

ちなみに以下のようなものが、うちのチームで良くあるemojiの使い方だ。

commit comment	意味
	ゴミを捨てた（要らないメソッド・空行を消した）
Typo	このスペルミスはカッコ悪いよねぇ〜
cosme	お化粧（コードをちょっと綺麗に整えた）

参考資料とか

• 英語でコミットを書こう
• 英語コミットコメントに使えるオシャレフレーズ集

英語でコミットコメント、っていうときに参考になると思う。
「英語でコミットを書こう」は、社内の開発に限らない、オープンソース活動なんかでも使える、むしろオープンソースを意識した分かりやすいコメントを目指す時の、最初の一歩になる。
「英語コミットコメントに使えるオシャレフレーズ集」は、上にも書いた「チームで言葉の意味を育てる」で有効活用したり出来る。

最後に

ごちゃごちゃ色々書いたけど、最終的に大事なのは、やっぱり「人に伝えること」なので、独りよがりにならず、「 相手がこのコミットを見た時にどう捉えるか 」を意識して書けば、自然と良いコミットコメントになるのではないか。
コミットコメントはドヤるためにあるんじゃないんだよ！