バージョン管理を使用しているときに、すべてのコードファイルに「変更ログ」を含めることに意味はありますか？
バージョン管理システムにより、コードの至る所に「変更ログ」を埋め込む必要がなくなるという印象を受けました。変更ログの継続的な使用を見てきました。これには、ストアドプロシージャの開始時に大きな長いブロックが含まれ、ファイルへの変更のために大きなセクションがブロックされ、次のようなコードが散らかっています。
// 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を適切に使用する方法が本当にわからないので、そのようなことはまったくしません」と言っているだけです。
どう思いますか？コメントとログの両方を使用していますか？ログだけ？ 1ブロック前に、John Smithがログを検索してDiffツールでコードファイルを比較するよりも、XYZをチェックする方法を1週間前に変更したコードを見ると、コーディングが簡単だと思いませんか？
編集：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.
ああ...そのコードベースについてお話ししたことのあるお話と私はそうします。
コードに埋め込まれた「変更ログ」は特に厄介です。リビジョンの差分をとると、さらに別の違いとして表示され、実際には気にしません。お使いのVCSを信頼してください-ほとんどの場合、誰が何を変更したかがすぐにわかる「非難」機能があります。
もちろん、本当に恐ろしいのは、実際のVCSログをソースファイルに埋め込むことができる「古い」VCSの機能でした。マージをほぼ不可能にしました。
特定のコミットメッセージによって自動的に入力されるプロジェクトごとに1つのChangeLogファイルがあります。
埋め込まれたChangeLogコメントはありません。私たちがそうした場合、私はそれらを削除し、それらを追加した人と「話し合い」をします。私はそれらがあなたが使っているツール、特にvcsを理解していないことを示していると思います。
ログのgrepを簡単にするコミットメッセージの形式があります。また、無用またはあいまいなコミットメッセージも許可しません。
私はコードソースファイル内の変更ログを個人的に嫌っています。私にとっては、変更は複数の場所で行わなければならないという点で、ソフトウェアエンジニアリングの原則に違反しているように感じます。多くの場合、変更ログ情報は完全に役に立たず、重要ではありません。私の控えめな意見では、コードをチェックインするときにソフトウェアの変更を文書化する必要があります。
しかし、私は何を知っていますか...
変更ログをソースコード内に保持する慣行を実装する上での援助がある場合、変更ログはクラスのpulic API /インターフェースに影響を与える変更に限定する必要があると思います。クラス内で、それを使用するコードを壊さない変更を行っている場合、変更ログにこれらの変更を記録することは、私の意見では混乱します。ただし、ソースコードファイルの先頭をチェックして、他のユーザーにとって何かが壊れている可能性のある変更についてのドキュメントを確認できると便利な場合があります。変更がAPIに与える影響と、変更が行われた理由の概要。
一方、私のショップは主にC＃に関することを行っており、常にインラインXMLコメントを使用してAPIを文書化しているため、パブリックAPIの変更に関するドキュメントを読むのは、インテリセンスを利用するのとほぼ同じくらい簡単です。
ソースファイル内の変更ログを主張することは、マシンに不必要な摩擦を追加するだけであり、バージョン管理システムを最初に実装する目的の1つを無効にすると思います。
私が最後に働いた会社には、17年の歴史、開発、そして毎年の更新を伴うソフトウェアがありました。 1つのバージョン管理システムから次のバージョン管理システムへのすべての移行で、コメントやチェックインノートが保持されるわけではありません。また、それらの年月のすべての開発者がチェックインのコメント/メモとの一貫性を維持していませんでした。
ソースコードにコメントが含まれているため、変更の考古学的履歴は、コメント化されたコードではなく、メモとして保持されていました。そして、はい、彼らはまだVB6コードを出荷しています。
チームの開発者が正しく使用している場合、バージョン管理により、コード内のこれらの変更ログコメントを置き換えることができます。
チームがチェックイン時にコメントを追加しない場合、または役に立たないコメントを残している場合、将来探している情報を見つけるのはかなり困難になります。
私の現在の会社では、チェックインのたびにコメントを送信する必要があります。それだけでなく、Jiraで各チェックインをチケットに添付することが期待されています。将来Jiraを見ると、チェックインされたすべてのファイルと、その問題がいつ発生したかが、残されたコメントとともに表示されます。それはかなり便利です。
基本的に、バージョン管理は単なるツールであり、チームがそのツールを使用して、求めている利点を提供します。チームの全員が、バグ修正の追跡とクリーンなコードリビジョンを提供するためにそれをどのように使用するかに同意する必要があります。
これは、VCSログが混乱し、VCSシステムの処理が困難だった時代の残り物です（80年代のバックエンドのどこかで覚えていました）。
あなたの疑惑は完全に正しいです。これらのコメントはヘルプよりも邪魔なものであり、最新のVCSはあなたが探しているものを正確に見つけることを可能にします。もちろん、あなた（そしてあなたの同僚）はおよそこれらすべての機能を操作する方法を30〜60分間学習します（これが、これらのコメントがまだ存在する理由だと思います）。
私はそれを（ほとんど）ジョージと一緒に保ちます。コード内のコメントが本当に正当化されるのは、コード自体ではすぐに表示されないものを説明する場合だけです。そして、それは良いコードではほとんど起こりません。コードにたくさんのコメントを含める必要がある場合、それはそれ自体の匂いであり、「リファクタリング！」と叫びます。
ストアドプロシージャのソースにはこれらを含めていますが、これは、クライアントに配置されているバージョンを正確に判断できる方法だからです。アプリケーションの残りの部分はコンパイルされて配布されるため、ソースにリンクするモジュールバージョン番号がありますが、SPはローカルのデータベース内コンパイルのためにソースとしてクライアントに配布されます。
私たちのレガシーPowerBuilderコードはまだそれらを使用していますが、それは特定の覗き見の快適さの要因と同じです。これも配布用にコンパイルされるため、（IMOが推奨）フリッグVCS履歴を使用します。
SVNを使用している場合、それを行うのは時間の無駄であり、まったく役に立ちません。
SVNには注釈機能があります。これにより、特定のファイルのすべての行を誰がいつ作成したかが正確にわかります。
誰もこれについて言及していなかったことに驚いていますが、これがライセンス要件に準拠する本来の理由ではありませんか？つまり、一部のライセンスでは、ファイルに加えた変更はファイル自体に記載する必要があるとしています。
変更ログのコメントは、後続の開発者が新しい要件に関してより良い質問をするのに役立つコードで非常に役立ちます。たとえば、開発者が、ある要件を満たすためにフレッドが6か月前にFooフィールドを必須にしたというコメントを見ると、開発者は、Fooをオプションにする最新のリクエストを実装する前に質問をする必要があることを知っています。複雑なシステムを扱う場合、利害関係者が異なれば、優先順位や欲望も異なる可能性があります。変更ログのコメントは、将来の問題を回避するためにこれらのトレードオフのどれが行われたかを文書化するのに非常に役立ちます。
ここで、すべての開発者が変更を加える前にすべてのコード行の完全な履歴を確認した場合、これらのコメントをコードに含めることは冗長になります。しかし、これはワークフローの観点からは非常に非現実的です。ほとんどの開発者は、誰が追加したか、その理由の履歴を調査せずに検証を変更するだけです。そして、テクノロジーの観点から、バージョン管理システムは「同じ"コード行がある行から別の行に移動した場合、または別のクラスにリファクタリングされた場合。コード内のコメントは見られる可能性がはるかに高く、さらに重要なのは、一見単純な変更はそれほど単純ではない可能性があることを後続の開発者に通知することです。
そうは言っても、コード内の変更ログコメントは比較的まれです。コードの一部がリファクタリングされるたびに、または真のバグが修正されるたびに、変更ログのコメントが追加されることを私は主張していません。しかし、元の要件が「Fooはオプション」であり、誰かがやって来て、要件を「ダウンストリームプロセスバーをサポートするためにFooが必要」に変更した場合、コメントの追加を強く検討します。将来のユーザー/アナリストがダウンストリームのBarプロセスに気付かず、Fooが必須にされた理由に気付かず、Fooを再度オプションにして、Barプロセスで頭痛の種となる可能性が高いためです。
そして、これは組織が、特に少数の開発者を抱える小企業からはるかに大規模な企業に成長するにつれて、ある程度の頻度でバージョン管理システムを変更することを決定する可能性があることを検討する前です。これらの移行により、変更ログのコメントが失われることがよくあります。コード内のコメントのみが保持されます。
コメントセクションで変更ログを維持し続ける理由は、使いやすさのためです。多くの場合、問題をデバッグするときは、ソース管理ファイルを開いてその中のファイルを見つけ、加えられた変更を見つけるよりも、ファイルの一番上までスクロールして変更ログを読む方が簡単です。