コミットメッセージを書くときに気をつけていること
コミットメッセージに関するブログを読んだので、自分がコミットメッセージを書くときに気にしてることを書いておく。
基本的な話
まずは Gitのコミットメッセージの書き方 を読んでおく。
コミットメッセージは "将来の同僚のため" に書く
3ヶ月後にチームに入った人が理解できる内容 になっているのが理想。
チームメンバーが分かる内容で満足すると、暗黙的な業務知識に依存したコミットメッセージになっていることがあるので注意。
XXXを追加/変更/削除しました はダメ
油断するとこういうメッセージを書いてしまいがち。
git-diff の内容を日本語で書いただけだと意味がないので、コミットメッセージで付加価値がつくように気をつける。
コミットした後に見直す
コミットした後、git show @ を実行して、以下の点を確認する。
- diffの全てをコミットメッセージで説明できているか？
- 関係ない変更が混ざっていないか？
- コミットメッセージを読んで「なぜ？」と自問する
- 更に Why を深掘りして書けないか？
参考にしたURLを残す
自分が知らなかったことは、たぶん他メンバーも知らない可能性が高い。
コードを書いていて参考になったWebページがあったら、コミットメッセージに残しておく。
GitHubのURLを固定する
- https://github.com/rails/rails/blob/master/README.md
- https://github.com/rails/rails/blob/v6.0.0.rc2/README.md
1だとmasterブランチが更新されると内容が変わってしまう可能性があるので、2のようにタグの入ったURLにする。
ちなみに、GitHubでファイルを表示しているときに y を押すとURLが master から blob に変わります。*1
URLを張りつつ、文面も引用してメッセージに含める
@sue445 さんのブログと半分同じなのですが、文面を引用して残すところが少し違うかな。
- コミットメッセージ単体だと意味が分からなくなる事が多い
- 自分がログを見ていたときに別ページを毎回開くのが面倒だった
- リンク先が将来も残っているとは限らない
コミットメッセージは長くても良い
コミットメッセージが短くて不足しているより、多少冗長でも変更理由が書いてある方が嬉しい。
コミットログは日本語でちゃんと理由を書いてあれば、ポエム的な事を書いても良いと思ってる。
— 神速 (@sinsoku_listy) June 22, 2019
仕事でRubyアップグレードしたときのログはこれ。
> Ruby 2.6.3では日本の新元号「令和」のサポートが追加されました。
> これで我々は令和時代のRubyistと言っても過言ではありません！
*1:下のヘルプ画像は ? で出ます
