コミットメッセージには、変更に対する「なぜ」を書く。
週末の余暇のうちに以下のツイートについてもう少しテキスト化しておく。
「コメント対応」というコミットメッセージへの指摘がめんどうなので、クライアントサイドでの git hook を用意した。配置を求めるのがなんだけど。 https://t.co/rbpS0DF2Cw
— Koichi ITO (@koic) 2016年11月14日
Git など使うことで、ソースコードへの変更理由について、5W1H に沿った変更履歴を知ることができることが理想。
- 「いつ (When) 」コードに対していつ変更を加えたのかはタイムスタンプを見れば分かる
- 「どこで (Where) 」コードに対して何を変更を加えたのかはリソース (file/dir) 名で分かる
- 「誰が (Who) 」コードに対して誰が変更を加えたのかは author を見れば分かる
- 「何を (What) 」コードに対してどうやって変更を加えたのかは diff を読めば分かる
- 「なぜ (Why) 」コードに対してなぜ変更を加えたのかはコミットメッセージを読めば分かる
- 「どうやって (How) 」コードに対してどうやって変更を加えたのかは実装を読めば分かる
このうち「なぜ (Why) 」については、結果事実となるソースコードからは読み取りづらい変更に至ったコンテキストが書けると好ましいと考えている。
GitHub での Pull Request をお昼のお仕事にもちいた開発以降に見かけるようになった「コメント対応」というメッセージは、そのソースコードの変更に至った情報がコミットログに対して紐づかないため好ましくないというのが表題の主張。またコメントから繋がる細かなリファクタリングと、本質的に問題のあった修正に対して十把一絡げに「コメント対応」とすると、重要な変更と些末な変更が混ざるといった次なる疑問手に繋がって行く (もう少し言うと master に入る前にできるだけ squash してトピックブランチでの作業中に発生する重要でない変更履歴はそもそもコミットに混ぜたくない派ではある) 。
一方で、大した変更理由でなければ大したことはコミットメッセージに書かない。例えば小さなリファクタリング系の変更であれば (2018年頃にはこれらのような絵文字運用を使うのをやめて、リファクタリング理由を書くようにした。理由は説明を省き過ぎているため。)Cosmetic :lipstick: :nail_care: というのを割とコミットメッセージの常套句として使っている。
ということで、Git フックをもちいて「コメント対応」というコミットメッセージをシステム的に防ぐ設定を Gist に書いておいたりしてた (ツイートに書いたとおり .git ディレクトリへの配布を求めるのが難点) 。
「コメント対応」という文言については個人的によく見かける文言にしているだけなので、お好みの正規表現で。
