バージョン管理にコメントを残したとしても、ソースコードに改訂履歴のコメントを残す必要があるという主張
(2011/06/12追記)
コメント欄でご意見いただいたので、追記しておきます。
ここでいう、バージョン管理は、いわゆるSubversionなどの、
いわゆる集中管理型を想定しています。
gitなどの分散管理型では、集中管理型では、
コミットコストが低い→集中管理型に比べ、コミットが頻繁になる→
→"「一つのチケットに対して複数のコミット」が基本とな"る
と理解しました。
(2011/06/12追記終わり)
改訂履歴のコメントとは、
// 課題xx 修正|追加|削除 start
...
// 課題xx 修正|追加|削除 end
みたいなやつ。
場合によっては、名前だったり、所属だったり、日付だったりも入れるかも知れない。
バージョン管理にコメント残すから、こういうのは要らないでしょ。という意見があるという話。
この手の主張って、結構聞く気がするのですが、
探してみたら、意外と見つかりませんでした。
もっとも探し方が悪いのかも知れませんが。
見つけたものをいくつか引用します。
バージョン管理にコメントを残せば、ソースコードに改訂履歴のコメントを残す必要はないという主張
修正コメントは時代遅れ！？
私は、修正コメントを、百害あって一利なし、のものと考えています。主な理由は、コードが汚くなる、修正が面倒になる、Diffツールを使った差分が台無しになる、この３点です。（もっとあるかもしれません。）
ソースコードの保守性の観点から私が嫌いなのが、「不要なコメント」です。
その際たるものが、修正箇所の最初と最後に「日付 名前 開始（終了）」を記入しているだけのコメントです。まっとうな開発であれば何らかのソースコードバージョン管理ツール（subversionやCVS）を使っているでしょうから、全くの無意味です（継続的な修正や機能追加でこういったコメントが累積していってはたまりません）。
CVSでソース管理をしているにも関わらず、ソースに
以前の履歴や修正内容が残されているのを見たことはありませんか？これらの記述は、大昔にソース管理ツールなどというものが
存在しなかった時代に用いられていた手法です。
こういった記述は、修正を繰り返す度にソースを汚していきます。これを改善するためにソース管理システムがあるのです。
修正内容は、SVN(CVS)のコミットコメントとして残すので
ソース上に記述する必要はありません。
コメントアウトしている箇所は、もうそれが必要無いと判断した時点で
遠慮なく削除しましょう。
何を修正したかのコメントはSubversionのほうにコミットするたびに記録しておけばいいので
ソースコードに直接コメントを書く必要はない。バージョン管理システムの履歴を見れば
今までにコミットした各バージョン毎にコメントが一覧でわかる。
しかし、今一緒に開発している同僚のSEは、「古いソースをコメントアウトしたり、コメントに日付を入れたりするのは、構成管理ツールが無かった頃の古いやり方だ。今はむしろやってはいけない風潮になっているから、すべきではない。」といい、そのやり方に反対しています。
はい、オールドタイプですみませんでした。。
バージョン管理にコメントを残したとしても、ソースコードに改訂履歴のコメントを残す必要はあると思う理由
一回のコミットに対して、一つの課題（チケット）を対象にする場合
一回のコミットに対して、一つの課題（チケット）を対象にする場合は、
一つのコミットコメントに対して、一つの課題が紐付くので、
バージョン管理の差分で出てくるソースコードの修正履歴が、
どの課題を対象としているのか明確なので問題ありません。
※−・・・1対1関係、→・・・1対多関係
一回のコミットに対して、複数の課題（チケット）を対象にする場合
一方、一回のコミットに対して、複数の課題（チケット）を対象にする場合、
例えば、関連する課題をまとめて修正した場合などは、
一つのコミットコメントに対して、複数の課題が紐付き、
複数の課題それぞれに対して、複数の修正箇所が紐付きます。
この場合、コミットコメントには二つの課題を対応した旨、
記載することになると思いますが、バージョン管理の差分で出てくるソースコードの修正履歴が、
一つのコミットに対して、複数の課題を対象にしているために、
どの課題を対象としているのか、コミットコメントを見ただけでは分かりません。
※−・・・1対1関係、→・・・1対多関係
想定問答
そんなの見れば分かるっていう意見もあると思いますが、
それは、どの機能がどのソースで実現されているかを理解している場合のみで、
ソースを読む人全員が、そうであるとは限りません。
また、複数の課題をまとめて対応した場合でも、
一回のコミットで、一つの課題のみ対象となるよう分けてコミットした方が良い
と思いますが、うまく分かれない場合があるのも事実です。
ソースコードの修正履歴は誰が見るのか
ソースコードのレビューア
一番ソースコードの修正履歴を見るのは、ソースコードのレビューアでしょう。
これは私自身がそうであったからこそ、このエントリが生まれているわけですが。
修正内容が良く分からないときは、担当者に確認する必要がありました。
まあ、これは比較的リアルタイムの話なので、問題になることは少ないかも知れません。
トラブル発生時の保守エンジニア
または、なにかトラブルが発生したときに、犯人探し、もとい、原因追及をするのに、
どのリビジョンで問題が発生したかを確かめるため、
ソースコードの修正履歴を見るということはあると思います。
この場合、修正からある程度時間が経っている可能性があり、
その上、ソースコードの修正履歴が、どの課題に紐づいているか分からないという状況だと、
ソースのどの部分がトラブルの原因になっているのか、
特定しづらいという問題があります。
影響調査時の保守エンジニア
同上。
