上手なコミットメッセージの残し方

2019年6月24日

皆さんこんにちは、末ちゃんです。

先日久し振りにお出かけをしたついでに写真を撮ろうと思ったら、土砂降りで悲惨な目に遭いました。
世界は僕に写真を撮らせまいという意思のようです。

さて、今回は上手なコミットメッセージということで、やっていきたいと思います。
これはコミットだけに関わらず、チケットタイトルや、議事録など、すべてのシチュエーションで有効だと思われます。

コミットメッセージとは

まずコミットメッセージとはなんたるかですが、今回Gitを前提にしてお話ししていきます。

Gitとはバージョン管理システムです。このGitにはコミットという概念があり、変更等の作業に対して変更のあったファイルとその行を記録し、それに対して任意にメッセージを残すことができます。
これがコミットメッセージにあたります。

コミットメッセージは何のためにつけるのかというと、それはもちろん後から見返すために使います。
いわば本の目次のようなものになるため、行った作業に対して的確に対応しつつ分かりやすく要約されていなければなりません。

この話がでるときよく使われるのが、「5W1H」です。

  • When
  • Where
  • Who
  • What
  • Why
  • How

5W1Hとはこれらになりますが、これらをコミットメッセージにしっかり入れ込んであげればいいわけです。

以下にサンプルを用意します。

まず最初に下記のデータがあるとします。

console.log('HELLO WORLD!');

これを以下のように変更します。

const flag = true;

if (flag) console.log('HELLO WORLD!');

flag が true のときにのみ console.log() を実行するように変更しました。
バージョン管理システムなしで運用している場合、こういった記録は手で書きしるすなりしか方法がありません。

しかしバージョン管理システムを使用すれば、先ほどの5W1Hを簡単に記録することができます。

試しにこの変更をGitでコミットして、ログを見てみます。

test2 (master)  % git log -1 --stat                                                                                                                                                                                                                              [18:19:16]
commit 9bef5ded7818ccbf293dd6458542cd71a41b362a (HEAD -> master)
Author: sueyoshi <example@example.com>
Date:   Mon Jun 24 18:18:52 2019 +0900

    fix - flagが真のときにのみメッセージが出力されるように修正
      常時ではなく条件を満たしたときのみにメッセージを出力したいため、判定処理を追加した

 index.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

このようにしてみると、

  • When → Date: Mon Jun 24 18:18:52 2019 +0900
  • Where → ファイル名 (index.js)
  • Who → Author: sueyoshi <example@example.com>
  • What → fix – flagが真のときにのみメッセージが出力されるように修正
  • Why → 常時ではなく条件を満たしたときのみにメッセージを出力したいため、判定処理を追加した
  • How → 後述

と、このようにこのコミットだけで5Wすべてが満たされました。

残る1Hについては、Diffをかけてあげればよくわかります。

-console.log('HELLO WORLD!');
+const flag = true;
+
+if (flag) console.log('HELLO WORLD!');

上手なコミット

コミットメッセージがなんたるか大体伝わったと思います。

さて、上手なコミットメッセージの書き方としてそもそも前提があります。
それは、1つの変更につき1つのコミットを発行する。ということです。

複数の変更を1つのコミットにまとめてしまうと、そもそもメッセージがカオス化しますし、そのコミットをRevert（なかったことにする）等したいときに、他の変更も巻き込んでしまいます。

故に細かくコミットは発行すべきなのです。

コミットメッセージをテンプレート化する

さて、やっと本題です。

PREFIX - SUBJECT
  BODY

上記のようにテンプレート化してメッセージを書くと分かりやすいです。

PREFIXには add や fix などのように単語ひとつでどのようなことをしたか伝わることを書きます。
このPREFIXの書き方についてはチームによって様々なので、そのプロジェクト等に合わせて変更すると良いでしょう。

SUBJECTには、ひと言の文章で変更の内容を記載します。
主にログを漁るときなどはこのSUBJECTをたよりにするため、短くかつ端的に情報を書き込みます。

BODYには、詳しい内容を記載します。
SUBJECTだけで全ての説明がすむならここは不要だと考えます。
ですが大体の場合そうではないので、具体的な内容をここに書きこみます。
今回の例では、「条件を満たしたときにのみメッセージを出したいために変更をおこなった」ということを記載しました。

また、BODYにはチケットURL等を貼り付けて補足させるのも悪くありません。

まとめ

いかがだったでしょうか。ただこれだけのことだったんですが。

皆さんの現場ではコミットメッセージが「修正した」とか、「表示がバグっていたのを直した」とかみたいなメッセージがあったりしませんでしょうか。
これでは後から見ても、「何をやねん！」って突っ込むことになってしまい、ひとつひとつコードを見て・・・みたいなことになりかねません。
それじゃ意味がないのです。

コミットメッセージだけでなく、あらゆる「記録」するという場面において、一目で端的に伝えられるメッセージを残すと言うことを意識すると良いでしょう。

あ、あとひとつ。他の人は「あなた」ではありません。思考パターンも違えば前提知識も違います。これで伝わるでしょ。という思考は大体トラブルの原因なのでご注意ください。

それではまたお会いしましょう！

Share Button