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

Question

私の同僚の何人かは、バグ修正について特別なコメントを使用しています。たとえば、次のようになります。

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

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

私にお知らせください。

score 34 · Accepted Answer

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

ただし、自明ではないことが行われている理由を説明するコメントを入れています。したがって、バグ修正によってコードの予測が難しくなり、明確にならなくなった場合は、その理由を説明します。

score 15 · Accepted Answer

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

score 6 · Accepted Answer

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

[Bug-Id] xyz ダイアログの問題。サイズ変更コードを abc に移動し、後で初期化するようになりました。

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

チェンジリスト 1234 で修正されました。

サイズ変更コードを abc に移動し、後で初期化するようになりました。

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

score 4 · Accepted Answer

4

ソリューションが特に巧妙であるか、理解しにくい場合のみ。

于 2008-09-23T21:18:04.310 に答える

score 4 · Accepted Answer

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

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

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

（はい、残念ながら、多くの場合、ソース管理がありません...内部のものについては、TFS追跡を使用しています）

score 4 · Accepted Answer

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

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

score 3 · Accepted Answer

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

score 2 · Accepted Answer

作業中のコード内のバグに関するコメントをいくつか目にする傾向がありますが、私の個人的な好みは、コードコミットを 1 つのバグにリンクすることです。私が言うとき、私は本当に 1 つのバグを意味します。その後、いつでも変更内容を確認して、どのバグに適用されたかを知ることができます。

score 2 · Accepted Answer

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

// <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.

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

score 2 · Accepted Answer

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

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

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

ソースにない場合は、発生していません。

ソース管理ソフトウェアの経験不足、不適切な分岐モデルなどにより、プロジェクトのソース履歴が失われた回数を数えることはできません。変更履歴が失われない場所は 1 つだけです。それはソースファイルです。

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

score 1 · Accepted Answer

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

score 1 · Accepted Answer

多くの場合、そのようなコメントは、元のコードがどのように見えるか、または元の悪い動作に関するコンテキストを実際に持っていないため、より混乱を招きます。

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

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

score 1 · Accepted Answer

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

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

score 1 · Accepted Answer

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

しかし、一見正しそうに見える (しかし微妙なバグがある) ものをより複雑なものに変更する場合は、何を行ったかを説明する短いコメントを追加するとよいでしょう。（または彼女は）あなたが正当な理由もなく物事を複雑にしすぎたと考えています.

score 1 · Accepted Answer

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

私は、バグ修正が行われたときにコードにコメントを入れる多くのプロジェクトに取り組んできました。興味深いことに、おそらく偶然ではありませんが、これらのプロジェクトは、ソース管理ツールをまったく使用していないか、経営陣から法定でこの種の規則に従うように義務付けられていました。

正直なところ、ほとんどの状況でこれを行う価値はありません。何が変わったのか知りたければ、Subversion のログと差分を見ます。

ちょうど私の2セント。

score 0 · Accepted Answer

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

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

score 0 · Accepted Answer

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

score 0 · Accepted Answer

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

これではなく：

//$DATE $NAME $TICKET //次の可哀想な人への有益なコメント

私はこれをします：

//次の貧しい魂への有益なコメント

score 0 · Accepted Answer

私は可能な限り多くの 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.

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

score 0 · Accepted Answer

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

そうしないと、チェックイン時に入力するメッセージに必要なすべての情報が含まれていないはずです。

乾杯、

ロブ

score 0 · Accepted Answer

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

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

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

21 に答える 21

Related

Reference