いいコミットをつくる - Git

書き古されたテーマではありますが、Gitのコミットについて改めて考えてみます。

いいコミットには何が重要か?

いいコミットをつくることは重要です。まず、コミットはどんなときに見られるのかを考えると、以下のケースが考えられます。

いつ

  • プルリクエストのレビュー時
  • バグや機能追加でのデバッグ時
  • 機能のリリース時

何を

  • コミットメッセージのタイムライン
  • コミットメッセージの詳細
  • コードの変更内容

コードを読む際は、実装の意図を汲み取る必要があります。それは、以下のような人とのコミュニケーションになりそうです。

誰が

  • プロジェクトを開発してきた人
  • プロジェクトを開発してきたがいまはいない人
  • 新しくプロジェクトに参加した人
  • 未来の自分

実装の詳細を理解するために、コミットは役立ちます。コミュニケーションの効率化という観点で考えると、以下の点が重要です。

  • ひとめでわかる
  • 背景が追える

これを満たしたコミットは人に優しいですし、開発のしやすさにもつながってくると思います。上記を前提として、詳細を説明してゆきます。

Subjectはひとめでわかるようにする

コミットのSubjectは、タイムラインで見ることが多いと想定できるので、なるべくひとめでわかるようにします。具体的には、「何を」「なぜ」実装したのかを書くといいです

例を見てみます。

1
トップページへのリンクの誤りを修正

上記の例では、「何を」=「リンクを修正した」ですが、リンクが誤っていれば修正する必要があることは明らかなので、「なぜ」を明記する必要は特段なさそうです。

ほとんどのSubjectは「なぜ」を含める必要はありませんが、まれに書いたほうがいい場合があります。

例を見てみます。

1
脆弱性対応のためライブラリAをアップデート

上記の場合、単にライブラリAをアップデートとするより、脆弱性対応のためとしたほうがコミットの重要度が伝わってベターかと思います(この場合、脆弱性の詳細やリンクを3行目以降に追加したりするかもしれません)。このように、「なぜ」を含めるかどうかも考えるといいSubjectを書けそうです。

逆に、「悪い」Subjectの例は以下のようなものです。

1
微修正

 

1
デザイン変更

 

1
処理の改善

このように、具体的に何をしたのかわからないSubjectは避けたほうがいいと考えます。

Subjectを書くコツですが、以下のような単語で始まる(日本語であれば終わる)ような文面を考えるといいと思います。

  • Fix - バグ修正
  • Add - 機能追加
  • Update - 機能修正/変更
  • Remove - 機能削除

こちらの記事が参考になるかもしれません。

Bodyは背景が追えるようにする

コミットのBodyは、背景が追えるようにしておくといいと思います。なぜなら、Bodyを確認するときというのは、主に詳細な経緯や実装内容を確認したい場合を想定できるからです。

背景を追うためには、「なぜ」が重要ですが、「なぜ」の説明には注意が必要で、5 Whysなどをつかって、本質的な実装背景を簡潔に説明できるのが理想です。

例を見てゆきます。

1
2
3
Subject: 関数Aのバグを修正

Body: APIが動いていなかったため。

(上記はSubjectもよくないですが…)「なぜ」が「動いていなかったから」となっています。ここはもう少し掘り下げて、以下のようにするといいと思います。

1
2
3
4
5
6
Subject: Foo APIでパラメーターAを配列で受け取れるように修正

Body: アプリのUIが変更され、パラメーターAの型が配列となったが、
関数Aが配列型に対応していなかったためAPIがエラーを返していた。

- https://参考リンク.com/issues/1

毎回ここまでやる必要はないと思いますが、複雑な仕様変更などが入ったときなど、この方法は有効です。

変更はスコープを小さくする

コミットのスコープは小さくします。小さくというのは、行数を抑えるという意味ではなく、責務を考え、余計な変更を含めないという意味です。2つ以上の変更を含めない、とも言い換えることができそうです。

余計な変更を入れ込まないことで混乱を避け、理解しやすいコミットを作ることができます。

これは上記で説明したSubjectとBodyをしっかり意識できていれば容易かと思います。

コミットに時間をかけていい

良いコミットを作るのは慣れていないと案外考えてしまうものです。しかし、コミットに時間をかけること自体は問題ないと考えます。時間をかけすぎるのもアレですが、以下のようなメリットがありそうな内であれば大丈夫です。

  • 小さく変更を加えながらテストする開発スタイルが身につく
  • レビューの時間を節約できる
  • 開発に関わる全員のデバッグ時間を節約できる

参考

このエントリーをはてなブックマークに追加