コミットコメントの書き方

ソースコードのコメントの書き方についてある程度情報が出回っているように思うが、コミットコメントの書き方についてはあまり情報が無い気がするのでちょっと書いてみる。自分が出来ているかはおいといてｗ

で、これはリポジトリとバグ管理システムとセットで考えなくちゃいけないと思っている。まあ要するにTracやRedmineを使ったチケット駆動開発前提の話です。つまりコミットコメントにはチケット番号を書け。以上、って話でもあるｗ

コミットにはタグやブランチ作成のコミットを除くと大きく分けて２種類あると思う。１つ目はバグ修正のためのコミットで２つ目は機能追加のためのコミット。リファクタリングは２つ目に属するとする。

コミットはバグ修正、機能単位つまりチケット単位で行うべきだと思ってる。複数のバグ修正のためのコミットを１回でやられるとどのコミットがどのバグ修正に関連付いているのかわからない。こうなっちゃうとたとえばブランチに施したバグ修正をトランクにポーティングしたいときとかに困る。そういう状況でなくとも１回のコミットの内容を把握しやすくすることは重要。

とはいえコミットの回数とバグ修正、機能単位の数の関係は１対１にはならず多対１になるだろう。

理由は修正が大きいようなバグ修正や機能追加を行っている場合にはとりあえず現時点で実装済みのものだけコミットしたいから。これに関してはチケットを分割することによって、コミットの回数とチケットの数を完全に１対１にするという考えもあるだろう。ただTracやRedmineはチケットの親子関係を定義できないのでこれはまだ難しいかなと思っている。

で、実際のコメントの書き方だが、バグ修正なら「〜の問題を修正 refs #1234」という感じになるだろう。バグの詳しい内容はバグ管理システムを見ればいい。コミットするときチケット番号だけだとたとえばTracのタイムラインを見たときになんのバグを修正したのかわからないのでちゃんとサマリーもいれる。この内容はバグ管理システムとほぼ同一になるはずなのでDRYじゃないかもしれないがこれは入れるべき。機能追加も「〜機能の実装　refs #1234」みたいな感じでいいと思う。

コードを編集するにあたっていろいろ悩んだことがあるならその内容も書く。たとえば「修正方法として〜と〜を考えたが、今回は〜という理由から〜を選択した。」とか。こういう内容が後になって重要になることがある。

あとバグを修正しないという判断をした場合はコミットも無いのでチケットのコメントにその理由を書く。

「コミットコメント」で検索するとトップにくる以下も参考になるかも。
-コミットのやり方 - まさたか日記