コードのメンテナンス：コードにコメントを追加するのか、それともバージョン管理に任せるのか？
バグの修正や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形式のコメントを使用して、課題追跡で詳細情報の場所をユーザーに通知することは優れたアイデアです。
コード内のコメントは、その時点でのコードisに関するコメントです。ある時点でスナップショットを撮ることは、コードの古い（またはさらに悪いことに、将来の）バージョンを参照するべきではありません。
VCSのコメントは、コードの変更方法に関するものです。彼らは開発についての物語として読むべきです。
今、すべての変更にはコメントを含める必要がありますか？ほとんどの場合、そうです。私が想像する唯一の例外は、予期された動作がすでに文書化されているが、バグのために得られた動作ではなかった場合です。これを修正すると、既存のコメントがより正確になるため、コメントを変更する必要はありません。バグ自体はチケット履歴とコミットコメントに文書化する必要がありますが、コードが奇妙に見える場合にのみコードに記述します。その場合、// make sure <bad thing> doesn't happenで十分です。
私が本当に感謝するコメントの1つのタイプは次のとおりです。
//これは、プロポーザル2のビジネスルール5に実装されています
または、要件を収集するために使用するあらゆるもの。
これには2つの利点があります。1つは、検索せずに特定のアルゴリズムを実装した理由を見つけることができること、もう1つは、要件ドキュメントに取り組んでいる/作成していないソフトウェアエンジニアとのコミュニケーションに役立つことです。
これは小さなチームには役に立たないかもしれませんが、要件を作成する分析がある場合、それは非常に貴重です。
コメントは優れたプログラミング手法であると彼らが言ったときにあなたのリードは正しいですが、例外があります。加えた変更ごとにコメントを追加することもその1つです。そして、あなたはこれがバージョン管理システムに属すべきであると言うことによって正しいです。これらのコメントを1か所に保管する必要がある場合は、VCSが適しています。ソースコード内のコメントは古くなり、保守されなくなる傾向があります。コメントは悪いコメントよりはるかに優れています。望ましくないのは、両方の場所（コードとVCS内）に同期していないコメントがあることです。目標は、コードの変更に対する真実の単一のソースを持つことによって、物事を維持することですDRY=.
他の人が言ったことに加えて、変更がシステム全体に波及効果をもたらす場合に何が起こるかを検討してください。変更リクエストを実装するプロセスでコアインターフェイスの一部をリファクタリングするとします。この種の変更は、重要な変更（クラスまたはメソッド名の変更）。 VCSにすべてを自動的に行わせるのではなく、そのような操作によって触れられたすべてのファイルを調べて、そのようなコメントで手動で注釈を付けることになっていますか？ 1つのケースでは、適切なリファクタリングツールを使用した5分弱のジョブに続いて再コンパイルを行って、ビルドに問題がないことを確認しているのに対し、もう1つのケースでは、1日の作業に簡単に移行できます。具体的なメリットは何ですか？
また、コードの一部を移動するとどうなるかを検討してください。私が作業しているデータベース開発者の1人は、「SQLの各行に変更が加えられたリビジョンで注釈を付ける必要があり、各ファイルに対して個別のリビジョン履歴を作成することになります。誰がいつ、なぜを変えたのか」変更が単一行の変更の順序である場合、それはちょっとうまくいきます。最近深刻なパフォーマンスの問題を修正したときのように、一時テーブルを導入する大規模なクエリの一部を分割し、新しいコードフローに適合するようにいくつかのクエリの順序を変更する場合も、うまく機能しません。確かに、以前のバージョンとの違いは、ファイルの約3分の2が変更されたため、ほとんど意味がありませんでしたが、チェックインコメントも「パフォーマンスの問題を修正するための大幅な再編成」のようなものでした。 2つのバージョンを手動で確認したときには、大きな部品が実際には同じであり、移動しただけであることがかなり明らかでした。 （そして、問題のストアドプロシージャは、通常、実行に30分以上かかってから数秒かかりました。そのときまでに、少なくとも短期的には、大幅なさらなる改善のための場所がほとんどなく、I/Oバウンドでした。 ）
ごく少数の例外を除いて、変更の追跡と問題の参照はVCS、IMNSHOの作業です
私は通常このルールに従います。変更が明白で、結果のコードで問題が発生しない場合は、以前の動作を大幅に元に戻したり、大幅に変更したりしないでください。バグ番号やその他の変更情報を追跡するためにVCSに任せます。
ただし、明らかではない変更がある場合、それはロジックを変更します。特に、明白でない方法で他の誰かが行ったロジックを大幅に変更します-「この変更はこれを行うことであり、バグ＃42742 "が原因です。このようにして、誰かがコードを見て「なぜここにあるのか？これは奇妙に見える」と疑問に思ったとき、彼は自分の前に何らかのガイダンスを持ち、VCSを介して調査を行う必要がありません。これはまた、人々がコードの古い状態に精通しているために他の変更を壊す状況を防ぎますが、それ以降に変更されていることに気づきません。
コード内のコメントは最小限で正確でなければなりません。価値のない欠陥/変更情報を追加します。バージョン管理を使用する必要があります。バージョンコントロールが少し良い変更方法を提供することがあります。ClearCaseUCMを使用します。 UCMアクティビティは、欠陥番号、変更領域などに基づいて作成されます（たとえば、defect29844_change_sql_to_handle_null）。
チェックインのコメントでは、詳細なコメントをお勧めします。
私は、背景情報に関する詳細、いくつかの副作用のために実装されなかったソリューションの詳細を含めることを好みます。
Pramagic Programmer およびCleanCodeは次のガイドラインにつながります
コード内の低レベルの知識を保持し、コードが属する場所にコメントを残し、他の高レベルの説明のためにコメントを予約します。
バージョン管理関連のコメントはソースファイルに属していません。彼らは混乱を加えるだけです。同じ場所に配置する必要がある可能性が高いため（ファイルの上部にあるコメントブロックのように）、並列ブランチがマージされると、コメントのみの厄介な競合が発生します。
バージョン管理から引き出される可能性のある追跡情報は、コードの本文に複製しないでください。これは、$Log$のようなRCSチェックアウトキーワードとその同類のようなばかげたアイデアに当てはまります。
コードがバージョン管理システムの範囲外に移動する場合、その履歴に関するコメントの追跡はコンテキストを失い、そのためその価値のほとんどを失います。変更の説明を適切に理解するには、リビジョンにアクセスする必要があるため、以前のバージョンとの差分を表示できます。
Linuxカーネルの一部の古いファイルには、大きな履歴コメントブロックがあります。これらは、バージョン管理システムがなく、tarballとパッチだけがあった時代にさかのぼります。