バージョン管理を使用しているときに、すべてのコードファイルに「変更ログ」を含めることは重要ですか？

バージョン管理システムにより、コードのいたるところに「変更ログ」を貼る必要がなくなるという印象を受けました。私は頻繁に変更ログの継続的な使用を見てきました。これには、ファイルへの変更のためにブロックされた大きなセクションを含むストアドプロシージャの開始時の大きな長いブロックが含まれます。

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

そして：

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

私に説明されたように、この理由は、VCSログをふるいにかけるのに時間がかかりすぎて、誰が何をなぜ変更したかを見つけようとしている間、コードファイル自体に関連する上部または近くにそれを持っているからです誰が何をいつ変更したかを簡単に確認できます。私はその点を見ていますが、冗長であり、「VCSを適切に使用する方法が本当にわからないので、そのようなことは一切気にしません。

どう思いますか？コメントとログの両方を使用していますか？ただのログ？John Smithが1週間前にXYZをチェックするようにメソッドを変更したコードブロックの上に表示されると、Diffツールでログを検索してコードファイルを比較する代わりに、コーディングが簡単になりますか？

編集：SVNを使用しますが、基本的にはリポジトリとしてのみ。ブランチ、マージ、ログ+ストレージ以外はありません。

私はコード内のコメントを削除する傾向があります。そして、削除というのは、偏見を持つということです。特定の機能が何かを行う理由をコメントで説明しない限り、コメントはなくなります。バイバイ。合格しないでください。

したがって、まったく同じ理由で、これらの変更ログも削除しても驚くことではありません。

コメントアウトされたコードや本のように読めるコメントの問題は、それがどれほど関連性があるのか​​を本当に知らないことであり、コードが実際に何をするのかについて誤った理解を与えることです。

あなたのチームはバージョン管理システムの周りに良いツールを持っていないようです。Subversionを使用していると言ったので、Subversionリポジトリを管理するのに役立つツールがたくさんあることを指摘したいと思います。Webを介してソースをナビゲートする機能から、変更セットを特定のバグにリンクする機能まで、これらの「変更ログ」の必要性を軽減する多くのことができます。

たくさんの人にコメントしてもらい、コメントを削除したのは間違いだと言います。私が見たコードの大部分はコメントされているのが悪いコードであり、コメントは問題を難読化しているだけです。実際、私がコードにコメントしたことがあるなら、私は彼らが私を殺したいと思うことは比較的確実だから、保守プログラマーに許しを求めていると確信できる。

しかし、コメントをjestで削除する必要があると言わないように、このDaily WTFの投稿（作業したコードベースから）は私のポイントを完全に示しています。

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

ああ...そのコードベースについてお話しできる話、そしてそれは、周りの最大の政府機関の1つによってまだ使用されていることを除いて、そうするでしょう。

コードに埋め込まれたこれらの「変更ログ」は特に重要ではありません。リビジョンを比較するとき、それらはさらに別の違いとして表示されますが、実際には気にしません。VCSを信頼してください-ほとんどの場合、誰が何を変更したかをすぐに表示する「非難」機能があります。

もちろん、本当に恐ろしいことは、ソースファイルに実際のVCSログを埋め込むことができる「昔の」VCSの機能でした。マージをほぼ不可能にしました。

特定のコミットメッセージによって自動的に入力されるプロジェクトごとに1つのChangeLogファイルがあります。

ChangeLogコメントは埋め込まれていません。もしそうなら、私はそれらを削除し、それらを追加する人と「話」をします。使用しているツール、特にvcを理解していないことを示していると思います。

ログのgrepを簡単にするコミットメッセージの形式があります。また、役に立たない、またはあいまいなコミットメッセージも許可しません。

私は個人的に、コードソースファイル内の変更ログを嫌います。私にとっては、ソフトウェアエンジニアリングの原則に違反しているように感じます。つまり、変更は複数の場所で行う必要があります。多くの場合、変更ログ情報はまったく役に立たず重要ではありません。私の謙虚な意見では、コードをチェックインするときにソフトウェアの変更を文書化する必要があります。

しかし、私は何を知っていますか...

ソースコード内に変更ログを保持する慣行を実装することに固執する場合、変更ログは、クラスのpulic API /インターフェイスに影響を与える変更に限定する必要があると思います。クラス内でそれを使用するコードを壊さない変更を行っている場合、これらの変更を変更ログに記録することは私の意見では散らかっています。ただし、ソースコードファイルの先頭をチェックして、他の人にとって何かが壊れている可能性のある変更に関するドキュメントを確認できると便利な場合があります。変更がAPIにどのように影響するか、変更が行われた理由の概要のみ。

一方、私のショップは主にC＃のことを行っており、APIのドキュメント化には常にインラインXMLコメントを使用するため、パブリックAPIの変更に関するドキュメントの読み取りは、インテリセンスを利用するのとほぼ同じくらい簡単です。

ソースファイル内の変更ログを主張することは、マシンに不必要な摩擦を追加するだけであり、そもそもバージョン管理システムを実装する目的の1つを無効にするものだと思います。

私が働いていた最後の会社には、17年の歴史、開発、年次更新があったソフトウェアがありました。あるバージョン管理システムから次のバージョン管理システムへのすべての移行が、コメントまたはチェックインノートを保持するとは限りません。また、その年のすべての開発者は、チェックインのコメント/メモとの一貫性を維持していませんでした。

ソースコードにコメントがある場合、変更の考古学的な履歴は、コメントアウトされたコードではなく、メモとして保持されていました。そして、はい、彼らはまだVB6コードを出荷しています。

チームの開発者が適切に使用している場合、バージョン管理はコード内の変更ログのコメントを置き換えることができます。

チームがチェックインに関するコメントを追加していない場合、または役に立たないコメントを残している場合、将来探している情報を見つけるのはかなり困難です。

現在の会社では、チェックインごとにコメントを送信する必要があります。それだけでなく、チェックインごとにJiraのチケットを添付する予定です。将来Jiraを見ると、チェックインされたすべてのファイルと、その問題についていつ残っているコメントを見ることができます。とても便利です。

基本的に、バージョン管理は単なるツールであり、チームがあなたが探している利点を提供するツールを使用する方法です。チームの全員が、バグ修正の追跡とクリーンなコードリビジョンを提供するために、それをどのように使用するかに同意する必要があります。

これは、VCSログが混乱し、VCSシステムの処理が難しかった時代の残り物です（80年代のどこかで、当時のことを覚えています）。

あなたの疑いは完全に正しいです。これらのコメントは助けというよりも障害であり、最新のVCSはあなたが探しているものを正確に見つけることを可能にします。もちろん、あなた（そしてあなたの同僚）は約を費やす必要があります。これらすべての機能を操作する方法を学習する30〜60分（実際、これらのコメントがまだ存在する理由だと思います）。

私は（ほぼ）ジョージと一緒にいます。コード内のコメントは、コード自体にすぐに表示されない何かを説明する場合にのみ正当化されます。そして、それは良いコードではめったに起こりません。コードにたくさんのコメントを入れる必要がある場合、それはそれ自体の匂いであり、「リファクタリングしてください！」と叫ぶ。

ストアドプロシージャのソースにはまだ含まれています。これは、クライアントでどのバージョンが使用されているかを正確に判断できるためです。残りのアプリケーションはコンパイル済みで配布されるため、ソースにリンクするモジュールバージョン番号がありますが、SPはローカルのデータベース内コンパイル用にクライアントにソースとして配布されます。

レガシーのPowerBuilderコードは引き続きそれらを使用しますが、それは特定の覗き見の安らぎの要因と考えています。これも配布用にコンパイルされるので、（IMOは当然のことながら）初期のVCS履歴を使用します。

SVNを使用している場合、それを行うことは時間の無駄であり、まったく役に立ちません。

SVNには非難機能があります。これにより、特定のファイルの各行を誰がいつ作成したかが正確にわかります。

変更ログのコメントは、後続の開発者が新しい要件に関してより良い質問をするのに役立つときに、コードで非常に役立ちます。開発者がコメントを見ると、たとえば、Fredがいくつかの要件を満たすために6か月前にFooフィールドを要求したということ、その開発者は、Fooをオプションにするための最新のリクエストを実装する前に質問をする必要があることを知っています。複雑なシステムを扱う場合、異なる利害関係者は異なる優先順位と異なる欲求を持つ可能性があります。変更ログのコメントは、将来の問題を回避するために、これらのトレードオフのどれを文書化するのに非常に役立ちます。

ここで、すべての開発者がコードのすべての行の完全な履歴をチェックしてから変更を加える場合、これらのコメントをコードに含めることは冗長です。しかし、これはワークフローの観点から非常に非現実的です-ほとんどの開発者は誰がそれを追加したのか、なぜその履歴を調査せずに検証を変更するだけであり、技術の観点からは、バージョン管理システムは「同じ「ある行から別の行に移動した場合、または別のクラスにリファクタリングされた場合のコード行。コード内のコメントは見られる可能性がはるかに高く、さらに重要なことは、一見単純な変更がそれほど単純ではない可能性があることに注意するよう後続の開発者に促すことです。

ただし、コード内の変更ログのコメントは比較的まれです。少しのコードがリファクタリングされるたびに、または真のバグが修正されるたびに、変更ログのコメントを追加することを推奨しません。しかし、元の要件が「Fooはオプション」で、誰かが来て要件を「Fooはダウンストリームプロセスバーをサポートするために必要」に変更した場合、コメントを追加することを強くお勧めします。将来のユーザー/アナリストが下流のBarプロセスに気付かない可能性が高く、Fooが必要になった理由に気付かない可能性が高く、Fooを再びオプションにし、Barプロセスで頭痛の種を引き起こすように要求するからです。

これは、特に少数の開発者を抱える小さな会社からはるかに大きな会社に成長するときに、組織がある程度の頻度でバージョン管理システムを変更することを決定する可能性があることを考慮する前です。これらの移行により、多くの場合、変更ログのコメントが失われます。コード内のコメントのみが保持されます。

誰もこれに言及していないことに驚いていますが、これがライセンス要件に準拠する最初の理由ではありませんか？つまり、一部のライセンスでは、ファイルに加えた変更はファイル自体に記録する必要があると言っていますか？

コメントセクションで変更ログを維持し続ける理由は、使いやすさのためです。多くの場合、問題をデバッグするとき、ソース管理ファイルを開いてその中のファイルを見つけ、加えられた変更を見つけるよりも、ファイルの上部までスクロールして変更ログを読む方が簡単です