小さい頃はエラ呼吸

いつのまにやら肺で呼吸をしています。


開発者に読んでもらいたいSubversionのコミットログの書き方

Subversion


photo credit: nettsu via photopin cc

はじめに

ソースコードのバージョン管理にSubversionを使っているのですが、開発者によってコミットログの書き方がまちまちで、よく書かれているコミットログもあれば、全然役に立たないコミットログもあります。
他の人はどうやって運用しているのか気になって、コミットログの書き方を調べて、まとめてみました。

Subversion実践入門:達人プログラマに学ぶバージョン管理(第2版)
Subversion実践入門:達人プログラマに学ぶバージョン管理(第2版)
posted with amazlet at 13.06.22
Mike Mason
オーム社
売り上げランキング: 23,384
Amazon.co.jpで詳細を見る
１．コミットログを書く目的

コミットログを書く目的は、修正した理由や経緯を残すことで、後から修正内容をトレース（追跡）できるようにすることです。
コミットログは未来への布石です。コミットログが必要になるときというは、少しだけ後かもしれませんし、自分がいなくなったずっと後かもしれません。そうした場合に、なぜ直したのかがきちんと書かれていると、保守する人はとても助かります。

コミットコメントを書く際には、あとで自分が困らないように、ほかの人が困らないように以下のようなポイントに気をつけて書いています。
コミットコメントの書き方(我流) - 地平線に行く はてなブックマーク - コミットコメントの書き方(我流) - 地平線に行く

２．コミットログに書くこと

コミットログには、何をどうして直した(理由や経緯)かを書くと良いです。
何をどう直したかは修正内容をdiffすれば確認できるのですが、なぜその修正を加えたかはソースコードに残らないことが多いため、コミットログに残しておきます。

ソースの修正理由は、修正内容よりも、修正した理由をできるだけ書いた方がいい。ソースを差分比較すれば修正内容は分かるので、理由が一言でもあれば、ソースを理解しやすくなる。
SVNのコミットログの書き方: プログラマの思索 はてなブックマーク - SVNのコミットログの書き方: プログラマの思索

不具合を修正した場合は、不具合修正とひとこと書いて、バグ管理番号を記述するだけで十分です。バグの内容や原因についてはBTSで管理します。BTSにパーマネントリンクがあるなら、URLを貼り付けても良いです。クリック１つでバグ票が参照できます。

３．コミットログに書かなくても良いこと

誰が直した、いつ直したという情報はコミットログに書く必要はありません。コミットした時点でSubversionがこれらの情報を保持してくれています。

４．コミットログの書式をチームで統一する

コミットログの書式はチームで相談しながら、決めると良いです。個人的に取り入れてみたいと思ったのは、以下のように【】で修正区分を書くというスタイルです。

一行目には、必ず変更の種別を書くようにしています。たとえば、
・機能追加
・仕様変更
・不具合修正
・リファクタリング
などです。
また、仕事の時はそれと一緒に件名も書いて、太括弧【】に囲んで記述しています。
コミットコメントの書き方(我流) - 地平線に行く はてなブックマーク - コミットコメントの書き方(我流) - 地平線に行く

統一されたスタイルで書くことでコミットログの検索効率が高くなります。用語もチームで統一しておくとなお良いです。

５．コミット時に論理的なまとまりを意識する

コミットログの書き方とは少しズレますが、コミットする単位についても書いておきます。
コミットするときは、論理的なまとまりを意識すると良いです。以下のサイトにまとまっていますが、1つのコミットにいろいろな修正を含めないほうが後からトレースしやすくなります。

よく言われることは1つのコミットには1つの小さな論理的にまとまった変更だけにする、というものです。

名前の変更やコードの移動などのリファクタリングをした後に変更したコードの周辺だけインデントが崩れることがあります。このようなときはインデントだけを直すコミットをします。typoの修正コミットに他の変更を混ぜるのはやめましょう。
クリアなコードの作り方: 意図が伝わるコミットのしかた - ククログ(2012-03-13) はてなブックマーク - クリアなコードの作り方: 意図が伝わるコミットのしかた - ククログ(2012-03-13)

番外編 コミットログの管理

１．コミットログを強制する

コミットログを必ず書きなさいとで周知することは簡単ですが、全員が確実に守ってくれる保証はありません。忙しくなってくると、コミットログはとても雑になってきます。
以下のサイトでは、Subversionのフックスクリプトを利用して、コミットログの記述を強制させる方法が紹介されています。

２．コミットログをメールでチェックする

Suversionにはフックスクリプトを利用して、コミット情報をメールで通知する機能があります。
これを利用して管理者がコミットログのチェックを行い、不備があれば是正させることもできます。

関連エントリ