コード内のバグ修正に特別なコメントを使用していますか?

Question

私の同僚の中には、バグ修正に関して次のような特別なコメントを使用する人もいます。

// 2008-09-23 John Doe - bug 12345
// <short description>

これには意味がありますか?
バグ修正については特別な方法でコメントしますか?

私にお知らせください。

Answer 1

私はそのようなコメントは入れません。ソース管理システムはすでにその履歴を保持しており、ファイルの履歴をログに記録することができます。

ただし、明らかではないことが行われる理由を説明するコメントを入れます。したがって、バグ修正によってコードの予測可能性や明確さが低下する場合は、その理由を説明します。

Answer 2

時間が経つにつれて、これらが蓄積され、乱雑になる可能性があります。コードを明確にし、明らかではない可能性のある関連する問題についてコメントを追加し、バグの詳細を追跡システムとリポジトリに保存することをお勧めします。

Answer 3

最新の情報を維持するのが難しいため、実際のソースにはコメントしない傾向があります。ただし、ソース管理ログと問題トラッカーにリンク コメントを入れています。例えばPerforce で次のようなことを行うとよいでしょう。

[Bug-Id] xyz ダイアログの問題。サイジングコードをABCに移動し、後で初期化します。

次に、問題トラッカーで次のようなことを行います。

変更リスト 1234 で修正されました。

サイジングコードをABCに移動し、後で初期化します。

そうすれば良い歴史的標識が残るからです。また、コードの特定の行が特定の方法である理由を知りたい場合は、ファイル履歴を見るだけで簡単になります。コード行を見つけたら、私のコミット コメントを読んで、それがどのバグに対するもので、どのように修正したかを明確に確認できます。

Answer 4

解決策が特に巧妙であるか、理解するのが難しい場合に限ります。

Answer 5

私は通常、自分の名前、電子メール アドレス、日付を、変更内容の簡単な説明とともに追加します。コンサルタントとして、他の人のコードを修正することが多いためです。

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

こうすることで、コードの所有者、または私の後に来る人々が何が起こったのかを把握し、必要に応じて私に連絡することができます。

(はい、残念なことに、多くの場合、ソース管理がありません...内部的なものには TFS トラッキングを使用します)

Answer 6

これはその時は良いアイデアのように思えますが、すぐに手に負えなくなります。このような情報は、ソース管理システムとバグ トラッカーをうまく組み合わせて使用​​すると、より適切に取得できます。もちろん、何か厄介なことが起こっている場合は、状況を説明するコメントが役に立ちますが、日付、名前、バグ番号は役に立ちません。

私が現在職場で取り組んでいるコードベースは20年ほど前のもので、数年前にこのようなコメントがたくさん追加されているようです。幸いなことに、彼らは 90 年代後半にすべてを CVS に変換してから数年後にそれをやめました。ただし、そのようなコメントは依然としてコード全体に散在しており、現在のポリシーは「コードを直接操作している場合はコメントを削除するが、それ以外の場合は残す」となっています。特に同じコードが何度も追加および削除されると、追跡するのが非常に困難になることがよくあります (確かに、それは起こります)。また、日付は含まれていませんが、日付を見つけるために古いシステムで検索する必要があるバグ番号が含まれているため、誰も知りません。

Answer 7

このようなコメントがあるため、Subversion ではコミットごとにログ エントリを入力できます。コード内ではなく、ここにこれを配置する必要があります。

Answer 8

バグ修正に単純ではないものが含まれている場合はそうしますが、多くの場合、バグ修正に長い説明が必要な場合は、修正が適切に設計されていないことの表れであると考えます。場合によっては、変更できないパブリック インターフェイスを回避する必要があるため、これが次のような種類のコメントのソースになる傾向があります。

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

他の場合には、ソース管理のコミット メッセージを使用して変更に注釈を付けます。

Answer 9

仕事ではコード内のバグに関するコメントを目にする傾向がありますが、私の個人的な好みは、コードのコミットを 1 つのバグにリンクすることです。私が 1 つと言っているのは、実際には 1 つのバグを意味します。その後、いつでも行われた変更を確認して、それらがどのバグに適用されたかを知ることができます。

Answer 10

このスタイルのコメントは、開発者全体にさまざまなスキルやビジネス知識がある複数の開発者環境では非常に価値があります (例:- どこにでも）。

経験豊富で知識のある開発者にとっては変更の理由は明白かもしれませんが、新しい開発者にとっては、コメントを見てよく考え、変更する前にさらに調査する必要があります。また、システムがどのように機能するかについてさらに学ぶのにも役立ちます。

ああ、「ソース管理システムにそれを入れただけです」というコメントについての経験からのメモ:

それがソースにない場合、それは起こりませんでした。

ソース管理ソフトウェアの経験不足や不適切な分岐モデルなどが原因で、プロジェクトのソース履歴が失われた回数は数え切れません。変更履歴は1つしかありません 失われることはありません - それはソースファイルにあります。

通常、最初にコメントをそこに配置し、チェックインするときに同じコメントをカットアンドペーストします。

Answer 11

いいえ、そうではありません。コード内にそのような落書きが散らばるのは嫌いです。バグ番号は、バージョン管理システムへのコミット メッセージ内で追跡することも、関連するコミット メッセージをバグ追跡システムにプッシュするスクリプトによって追跡することもできます。これらがソースコードに含まれるとは思えません。将来編集しても混乱するだけです。

Answer 12

多くの場合、このようなコメントは、元のコードがどのようなものであったか、または元の悪い動作についてのコンテキストが実際にはわからないため、さらに混乱を招きます。

一般に、バグ修正によりコードが正しく実行されるようになった場合は、コメントを付けずにそのままにしておきます。正しいコードをコメントする必要はありません。

バグ修正によって物事が奇妙に見える場合や、バグ修正によって通常とは異なる何かがテストされる場合があります。その場合は、コメントを付けるのが適切かもしれません。通常、コメントはバグ データベースの「バグ番号」を参照する必要があります。たとえば、「バグ 123 - ユーザーが 640 x 480 の画面解像度を使用している場合の奇妙な動作を説明する」というコメントがあるとします。

Answer 13

コードを数年間保守し続けた後にそのようなコメントを追加すると、コードを読むことができなくなるほど多くのバグ修正コメントが追加されることになります。

ただし、正しく見える (しかし微妙なバグがある) ものをより複雑なものに変更する場合は、変更内容を説明する短いコメントを追加するとよいでしょう。こうすることで、次にこのコードを保守するプログラマーがコードを元に戻さないようにすることができます。 （または彼女は）あなたが理由もなく物事を複雑にしすぎていると考えています。

Answer 14

いいえ。私は Subversion を使用しており、変更をコミットする動機の説明を常に入力します。通常、解決策を英語で再度説明することはせず、代わりに加えられた変更を要約します。

私は、バグ修正が行われたときにコードにコメントを追加する多くのプロジェクトに取り組んできました。興味深いことに、そしておそらく偶然ではないでしょうが、これらのプロジェクトは、いかなる種類のソース管理ツールも使用していないか、管理者からの法定事項によってこの種の慣例に従うことを義務付けられていました。

正直に言うと、ほとんどの状況でこれを行う価値はあまりありません。何が変わったのか知りたければ、Subversion ログと diff を調べます。

私の2セントだけです。

Answer 15

コードが修正された場合、そのコメントは役に立たず、誰にとっても興味深いものではなく、ただのノイズになります。

バグが解決していない場合、コメントは間違っています。それなら理にかなっています。:) したがって、実際にバグを解決できなかった場合は、そのようなコメントを残してください。

Answer 16

特定のコメントを見つけるために使用する DKBUGBUG - これは、David Kelley の修正とレビュー担当者が簡単に特定できることを意味します。もちろん、これに日付やその他の VSTS バグ追跡番号なども追加します。

Answer 17

VCS が保持するメタデータを複製しないでください。日付と名前は、VCS によって自動的に追加されるはずです。チケット番号、変更を要求したマネージャー/ユーザー名などは、コードではなく VCS コメントに記載する必要があります。

これよりも:

// $ date $ name $ choote //次の貧しい魂への便利なコメント

私だったらこうします:

//次の哀れな魂への有益なコメント

Answer 18

コードがソース管理リポジトリへの直接アクセスから離れたライブ プラットフォーム上にある場合は、ライブ システム上のバグ修正の一部として行われた変更を強調表示するコメントを追加します。

それ以外の場合、チェックイン時に入力するメッセージに必要な情報がすべて含まれている必要はありません。

乾杯、

ロブ

Answer 19

サードパーティのライブラリ/コンポーネントのバグ修正/機能強化を行うとき、私はよくコメントを付けます。これにより、新しいバージョンのライブラリ/コンポーネントを使用する必要がある場合に、変更を見つけて移動することが簡単になります。

私自身のコードでは、バグ修正についてコメントすることはほとんどありません。

Answer 20

私は複数人で取り組むプロジェクトには携わりませんが、単体テストに特定のバグに関するコメントを追加することがあります。

バグなどというものは存在せず、テストが不十分なだけであることを忘れないでください。

Answer 21

私はできる限り TDD を行っているため (他の方法はすべて、際限なく労働を強いられるため、社会的自殺行為です)、バグを修正することはめったにありません。

ほとんどの場合、次のような特別なコメントをコードに追加します。

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

厳しいように聞こえますが、自分たちを「開発者」と呼ぶほとんどの人は、それ以外の発言に値しません。