steps to phantasien「ChangeLog の作法 つづき」より
以下、参照記事に倣い、変更履歴の事を ChangeLog と表現する事にする。
ChangeLog というものは普通は書くのが面倒なので、ある程度の割り切りが大事である。
あなたのプロジェクトでは ChangeLog をどのように扱っているだろうか？そもそも書くべき事（或いは書き方）がプロジェクトで決まっていないという事はないか？コーディング規約やドキュメントの書き方は馬鹿みたいに神経質に決めるくせに ChangeLog は全く無頓着ではないか？ChangeLog をソースコードに書いてしまい、ソースコードが ChangeLog だらけになっていないか？或いは異常に厳しいルールを強いていないか？
私は ChangeLog を次のように使っている（取り敢えず Subversion の話）。
「何の為にその Commit をしたのか」をごくごく簡単に書く程度である。「バグ No ～ の修正」とか「SQL の書き方を変えた」とか「～機能の追加」とか、その程度。どのファイルが変更されたとか、どの関数が変更されたとかのリストは書かない。そんなものを書くのはすごく面倒だし、書いたところで有用だとは思えない。そのリストが欲しければ Subversion のログを見ればよい。
ChangeLog は残っていたら便利なものなので「書かない」という選択肢はありえないが、あまりに律儀に書くようにルールを作ってしまうと弊害が出る。
数年前の話。あるプロジェクトのソースコード管理に CVS を使うように決めたのだが、そのプロジェクトの ChangeLog のルールは非常に鬱陶しいものだった（どうでもいいけど、CVS と CSV ってややこしいよね）。まず、変更したファイルのヘッダに、そのファイル中の何（どの関数、どの構造体など）がどういう理由（バグ修正なのか新規追加なのか）で変更になったかを書く。そして変更対象のヘッダにも書く。例えば、ある関数を変更すればその関数の直前にコメントとして書く。つまり、同じ事をファイルの先頭と関数の直前に書く。そして、更に同じ事を CVS の ChangeLog にも書く。三重の手間である。
こんな事をしているから、ソースコードファイルは ChangeLog だらけである。コードよりも ChangeLog の方が多い。private な関数（C 言語だったので static な関数）を追加するのにも ChangeLog を記述しなくてはいけないので、関数を追加するのが億劫になる。そして適切な関数分割をしなくなり、長くて複雑なスパゲッティ関数が乱発されていく。スパゲッティ関数が多いのでバグが多発する。バグが多いので更に ChangeLog が大量に書き込まれていく…。というように、負の無限ループが出来上がっていた。
これが ChangeLog の愚かな例である。
ChangeLog はごく簡単に意味のあるものを書くようにした方がよい。そうしないと、開発者の士気を削ぐ事になりかねない。悪いときには弊害もでる。