バグの修正/ CRの実装の一環としてコードに加えた変更ごとに、開始タグ、終了タグ、説明、解決策などのコメントを追加するよう求められています。
私の懸念は、これが付加価値を提供するかどうかです。現状では、バージョン管理履歴にすべての詳細があります。これは、すべての変更を追跡するのに役立ちますか？
しかし、私のリードは、コメントを「良い」プログラミング手法として主張しています。彼らの議論の1つは、CRのスコープを変更/変更する必要がある場合、コメントがないと面倒になることです。
変更は主にコードの中間にあると考えると、私たちが行うすべての変更にコメントを追加することは本当に役立つでしょうか？バージョン管理に任せてはいけませんか？
回答:
あなたは、絶対に正しい。変更の追跡は、バージョン管理システムの仕事です。コミットを行うたびに、何が行われたかを説明するコミットメッセージを作成し、これがバグ修正である場合はバグ追跡システムを参照する必要があります。コードにコメントを入れる
// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX
バグを修正するたびに、コードがすぐに読めなくなり、メンテナンスできなくなります。また、同じ情報を2か所で複製することになり、混乱がさらに悪化します。
コメントをバグ追跡に使用したり、コードの実行内容を説明したりしないでください。彼らはあなたがなぜXをやっているのか、なぜあなたがこの特定の方法でXをやっているのかを説明すべきです。コードのブロックが何をしているのかを説明するコメントを書く必要があると感じたら、それはコードの匂いで、このブロックを説明的な名前の関数にリファクタリングする必要があることを示します。
代わりに
// fixed bug XXXXX on 10/9/2012
あなたは言うコメントがあるかもしれません
// doing X, because otherwise Y will break.
または
// doing X, because doing Y is 10 times slower.
仕事に最適なツールを使用してください。 バージョン管理システムは、バグ修正とCRが行われたときに記録するための最適なツールである必要があります。日付と変更者を自動的に記録します。メッセージを追加することを決して忘れません（コミットメッセージを要求するように設定している場合）。間違ったコード行に注釈を付けたり、誤ってコメントを削除したりすることはありません。また、バージョン管理システムが既にコメントよりも優れている場合、コメントを追加して作業を複製するのは愚かなことです。
ソースコードの可読性は最重要です。すべてのバグ修正と作成されたCRの完全な履歴を与えるコメントが散らかったコードベースは、非常に読みにくくなります。
ただし、コメントを完全にスキップしないでください： 良いコメント（すべてのバグ修正とCRの開始/停止/説明/解決策をきちんと文書化しない）は、コードの可読性を高めます。たとえば、バグを修正するために追加するトリッキーなコードまたは不明瞭なコードの場合// fix ISSUE#413、問題トラッカーの詳細情報の場所をユーザーに伝えるフォームのコメントは素晴らしいアイデアです。
fix ISSUE#413コードの良いコメントではありません。外部のドキュメントを参照しなくても、コードを理解できるはずです。乱数を与える代わりに、コードのこのトリッキーな部分が何をする必要があるのかを実際に説明してください。それがコメントの目的です：明らかではないコードの部分を説明するため。
fix ISSUE#413は、問題が非常に複雑な場所（極端にOSと構成に依存するコーナーケース、または特定の悪い顧客データによってのみトリガーされる）であり、それを適切に記述すると、いくつかの段落。そのようなことは、問題追跡システムであるIMOによってうまく処理されます。それでも、ある種の簡単な説明がいいです。
fix ISSUE#413は完全に適切であり、さらに望ましいと言えます。問題レポートへのポインターを提供せずに要約するだけで、すべての詳細を必要とする将来の読者にとって生活がより困難になります。
fix ISSUE#413完全を期すためにコメントに含めることは問題ありませんが、松葉杖として使用しないでください。
コード内のコメントは、その時点でのコードの内容に関するものです。ある時点でスナップショットを撮ることは、古いバージョン（または、さらに悪いことに、将来のバージョン）のコードを参照すべきではありません。
VCSのコメントは、コードの変更に関するものです。開発に関するストーリーとして読む必要があります。
今、すべての変更にはコメントが含まれている必要がありますか？ほとんどの場合、はい。私が想像する唯一の例外は、予想される動作がすでに文書化されているが、バグのために得られたものではない場合です。修正すると、既存のコメントがより正確になるため、変更する必要はありません。バグ自体はチケット履歴とコミットコメントに記録する必要がありますが、コードが奇妙に見える場合のみコードに記録する必要があります。その場合、a // make sure <bad thing> doesn't happenで十分です。
私が本当に感謝しているコメントのタイプの1つは次のとおりです。
//これは、提案2のビジネスルール5に実装されます
または要件を収集するために使用するものは何でも。
これには2つの利点があります。1つは、検索せずに特定のアルゴリズムを実装した理由を見つけることができること、もう1つは、要件ドキュメントで作業/作成する非ソフトウェアエンジニアとのコミュニケーションに役立つことです。
これは小規模なチームでは役に立たないかもしれませんが、要件を開発する分析者がいる場合、非常に貴重なものになる可能性があります。
コメントは優れたプログラミング手法であると言う場合、リードは正しいですが、例外があります。変更のたびにコメントを追加することもその1つです。そして、あなたはこれがバージョン管理システムに属するべきだと言うことで正しいです。これらのコメントを1か所に保管する必要がある場合は、VCSが最適です。ソースコード内のコメントは古くなり、メンテナンスされない傾向があります。悪いコメントよりも優れたコメントはありません。望まないのは、同期していないコメント（コードとVCSの両方）にあることです。目標は、コードの変更に関する単一の真実の情報源を持つことにより、物事をドライに保つことです。
他の人が言ったことに加えて、変更がシステム全体に波及効果を持つ場合に何が起こるかを考えてください。変更要求を実装するプロセスでコアインターフェイスの一部をリファクタリングするとします。そのような変更は、些細な変更（クラスまたはメソッド名の変更）。VCSがすべて自動で行うことに依存するのではなく、そのような操作に触れたすべてのファイルを手動で調べて、そのようなコメントを注釈する必要がありますか？ある場合には、まともなリファクタリングツールを使用して5分以上の仕事を見てから、再コンパイルを実行してビルドを壊さないようにしますが、他の仕事は簡単に1日の仕事に入れることができます。具体的なメリットは何ですか？
また、コードの一部を移動するとどうなるかを考慮してください。私が協力しているデータベース開発者の1人は、主に「SQLの各行には、それが変更されたリビジョンを注釈する必要があります。そして、ファイルごとに個別のリビジョン履歴を作成する必要があります。誰がいつ、なぜ、何を変えたのか」。それは変更が行われたときに大丈夫です単一行を変更する順序で。深刻なパフォーマンスの問題を修正するために最近行ったように、一時テーブルを導入する大きなクエリの一部を分割し、クエリの順序を新しいコードフローに合わせて変更すると、うまくいきません。確かに、以前のバージョンとの差分は、ファイルの約3分の2が変更されたため、ほとんど意味がありませんでしたが、チェックインコメントも「パフォーマンスの問題を修正するための主要な再編成」のようなものでした。2つのバージョンを手動で見るまでに、大きな部分は実際には同じで、動き回っているだけであることが明らかになりました。（そして、問題のストアドプロシージャを実行するのに定期的に30分以上かかっていたものから、数秒かかりました。その時までに、
ごくわずかな例外を除き、変更の追跡と問題の参照は、VCS IMNSHOの仕事です。
私は通常、このルールに従います：変更が明白であり、結果のコードが問題を引き起こさず、以前の動作を実質的な方法で元に戻さないか、大幅に変更しない場合-それをVCSに任せて、バグ番号およびその他の変更情報を追跡します。
ただし、明らかではない変更がある場合は、ロジックを変更します。特に、他の人が行ったロジックを非自明な方法で大幅に変更する場合は、「この変更はこれを行うことで、バグ＃42742 "が原因です。このように誰かがコードを見て「なぜこれがここにいるのか、これは奇妙に見える」と疑問に思うとき、彼は彼の前にいくつかのガイダンスがあり、VCSを介して調査する必要はありません。また、これにより、コードの古い状態に精通しているが、その後変更されたことに気付かないため、人々が他の人の変更を壊すような状況を防ぐことができます。
バージョン管理関連のコメントはソースファイルに属しません。煩雑になるだけです。ファイルの先頭にあるコメントブロックなど、同じ場所に配置する必要がある可能性が高いため、並列ブランチをマージするときにコメントのみの迷惑な競合が発生します。
バージョン管理から取得できる追跡情報は、コードの本文に複製しないでください。これは、RCSチェックアウトキーワード$Log$やその同類のような馬鹿げたアイデアに当てはまります。
コードがバージョン管理システムの範囲外に移動すると、その履歴に関するコメントの軌跡はコンテキストを失うため、その価値のほとんどが失われます。変更の説明を適切に理解するには、リビジョンにアクセスする必要があります。そのため、以前のバージョンとの差分を表示できます。
Linuxカーネルの一部の古いファイルには、大きな履歴コメントブロックがあります。それらは、バージョン管理システムがなく、単にtarballとパッチがあった時代にさかのぼります。
コード内のコメントは最小限で正確でなければなりません。欠陥/変更情報の追加は重要ではありません。バージョン管理を使用する必要があります。いつかバージョン管理が変更のより良い方法を提供します-ClearCase UCMを使用します。UCMアクティビティは、欠陥番号、変更エリアなどに基づいて作成されます（defect29844_change_sql_to_handle_nullなど）。
チェックインコメントでは詳細なコメントをお勧めします。
いくつかの副作用のため実装されていないソリューションの詳細、背景情報に関する詳細を提供することを希望します。
Pramagic ProgrammerとCleanCodeは次のガイドラインにつながります
コードの下位レベルの知識を、それが属する場所に保持し、他の高度な説明のためにコメントを予約します。