🌟

良いコミットメッセージのルールメモ

2022/04/29に公開

1. はじめに

開発において、メッセージを書く機会は多い。
コード/テストコード/コミットログ/コードコメントなど。
これらは、書く時間より読まれる時間のほうが長いので、書く時のコストより読む人にとってのコストを意識して、書くべき。

各々については、下記を意識すると良い。

対象 記述内容で意識すること
コード How (どのように動かすか)
テストコード What (テスト対象コードの仕様は何をするものか)
コミットメッセージ Why(コードやテストコードから読み取れない、「それはなぜその変更をしているのか」という情報)
コードコメント Why not(なぜやってないかの理由)
コードの説明をしてしまうと、二重管理になってしまう為、避ける。

例:ここは XXX を使うべきだが、hogehogeの理由で仕方なく YYY を使っている)

2. なぜ良くしたいか

  • チーム作業において、円滑な共同編集ができるようにしたい。
  • 「良い変更履歴」を定義しルール化することで、認識ずれや理解やレビューにかかる時間のロスを減らす。
  • コミットのメッセージから、コミットの内容がある程度予想できるようにすることで、他のメンバーが理解にかかる時間を短縮したい。

3. いいコミットメッセージの定義

3.1. なぜそのコードの変更をしたのかがわかる

望ましいのは、コードをどのように変更したのかではなくなぜコードを変更したのかが書かれていること。
コードをどのように変更したのか、はコードの変更履歴を見ればわかるが、「なぜコードを変更したのか」はコードの変更履歴だけではわからない為。また、なぜコードを変更したのかが説明できるコミットの粒度にするべき。

  • 1つの目的に対して、1つのコミットとする
  • 意味のない(なぜを説明できない)コミットはまとめる
  • コミットは、プリリクエストによるレビュー時に、見られる前提で作る(レビューしやすいコミットを心がける)

3.2. ぱっと見で理解しやすい

何のコード変更なのかがカテゴライズされている、以下のような「プレフィックス(後述)」を先頭に付ける。

3.3. 関連する情報への誘導

コードの差分だけでは読み解けない、書き手の背景を理解する上で必要な情報を、(存在する場合)書く
たとえば仕様が記載されたドキュメントURLや、関連チケット番号、チャットツールのメッセージURLなどをコミットメッセージに書くなど。

4. 具体的なルール

4.1. コミットサマリの先頭には、プレフィックスをつける

プレフィックス 説明
feat: 新機能
fix: バグの修正
docs: ドキュメントのみの変更
style: コードの動作に影響しない、見た目だけの変更(スペース、フォーマット、欠落の修正、セミコロンなど)
refactor: バグの修正や機能の追加ではないコードの変更
perf: パフォーマンスを向上させるコードの変更
test: 不足しているテストの追加や既存のテストの修正
chore: ビルドプロセスやドキュメント生成などの補助ツールやライブラリの変更

5. コミットメッセージ例

過去形にしない。(可能であれば)影響範囲(スコープ)が想像できる内容にする。

  • ❌ 不具合が起きていたので、修正した
  • ❌ apidoc更新
  • ❌ レビュー指摘対応
  • ⭕️ refactor: 重複する関数の記述を1つにまとめた
  • ⭕️ refactor: XXXという変数がXXXXという誤解を招いたため、より意味のある名前に変更
  • ⭕️ refactor: ugafugaというメソッドは非推奨になったので推奨されるメソッドに変更
  • ⭕️ fix: hogehogeというサードパーティモジュールにはこういう脆弱性があるので脆弱性がないものに変更
  • ⭕️ doc: typo
  • ⭕️ perf: ユーザ一覧画面にて、必要なデータをDBから取得するロジックでN+1が発生していたので、実行しているクエリの条件式でin句を使うように修正

あとは、メッセージの先頭に絵文字を入れて、モチベーションを上げるカルチャーも一部ではあるらしい(あまり使わない)

人間と機械が読みやすく、意味のあるコミットメッセージにするための仕様

「Conventional Commits」という仕様がある。

概要は、下記のスライドがわかりやすかった。

https://speakerdeck.com/cocoeyes02/lets-use-conventional-commits

ただ、このルール、覚えるのも大変だし、チーム内で共通認識取るのも大変そうだ。
と、思っていたら、vscode拡張があった。

https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits

使ってみたところ、大変使い心地が良かった。
この拡張を共有すれば、チーム内の統一もやりやすそうだ。

 2022-05-13 230459

6. REFERENCE

GitHubで編集を提案

Discussion