Subversionのコミットコメントは、人によって多々書き方が違います。
ただ、後でコミットの内容を確認した時に
- 何も書かれていなかった
- 書いてあっても一行だけだった
となっていて、詳細が分からず、本人に聞いたりドキュメントを探して確認する羽目になったことが何回もあります。
そうした経験から、コミットコメントを書く際には、あとで自分が困らないように、ほかの人が困らないように以下のようなポイントに気をつけて書いています。
一行目には、変更種別を書く
一行目には、必ず変更の種別を書くようにしています。
たとえば、
- 機能追加
- 仕様変更
- 不具合修正
- リファクタリング
などです。
また、仕事の時はそれと一緒に件名も書いて、太括弧【】に囲んで記述しています。
（例：【不具合修正：ログイン画面】）
こうすると、変更理由をヒストリー一覧から探しやすくなります。
また、あとで見返したときに「このリビジョンで、リファクタリングなのに動作が変ったからバグ」だとか「このリビジョンで動作が変ったけど、仕様変更だから問題ない」とかの判断がしやすくなります。
逆にいえば、これがないと「ここで動作が変ったのは仕様変更だから？それともバグ？」ということになり、確認をしなくてはならなくなってしまいます*1。
Why と What を詳細に書く
コミットコメントで大事なことは、他の仕事と同じで5W1Hなのかなと思います。
このうち、Who(誰が)、When(いつ)、Where(ソースコードのどこを)、How(どのように)は自動で Subversion が管理してくれるので特に書かなくてもいいともいます。
なので、自分は残りの Why(どうして)/What(何を)をできるだけ細かく書くようにしています。
具体的には、以下のような点です。
- 不具合修正なら不具合の内容/原因
- 仕様変更なら元の仕様/変更後の仕様（必要であれば経緯）
- リファクタリングなら元の欠点と修正方法
また、参考にしたURLがあれば、合わせて記述しておくようにしています（特に、ライブラリやブラウザ、OSのバグは、URLを残しておくことによってあとで再び調べる手間を削減できます）。
書かないこと
不具合修正の時に、「xxクラスを直した」「xxフラグの値を変更した」とだけ書いてあることがありました。
でも、それはWhere、Howといった、ソースや差分を見れば分かる情報です。
なので、この辺はあまり書きません。
逆に、「どういった不具合を直したのか」「なぜそれを変更すると直るのか」といった、ソース上に直接かかれていない情報*2の方が重要ですし、それをしっかり書くようにしています。
他の人の反応
飲みの席で、ほかのチームの方とこのネタで意気投合したことがありました。
驚いたことに、その方も自分と同じような書き方をしてらっしゃいました。
(そして、チーム内に書かなかったりする人がいるのも同じでした・・・)
使っているバージョン管理システムが違うので、互いのコミットコメントを見たことはなかったのですが、経験を重ねると自然と同じ様なやり方になっていくようです*3。
それなので、ここに書いたことは我流であまり自信はないのですが、方向性としてはたぶんあっているのかなぁと思います。
