バグ番号のコメント

https://stackoverflow.com/questions/163232

03-07-2019
|

質問

追加する理由

// Bug 1024

ソース管理されたコードベースにコメントしますか？ほとんどのバグ追跡およびソース管理システムは、この情報を追跡するために装備されています。ソース管理では、チェックインでラベルまたはコメントを使用できます。バグトラッカーでは、リビジョン番号をバグの解決に追加できます。では、なぜコードをコメントするのですか？これらのコメントの関連性は非常に短命であり、コードベースを散らかす傾向があるため、特にです。

解決

これらのいずれかが先日コードベースで役立ったことがわかりました。

「ワークフローの後半で初期化関数を2度目に呼び出すのはなぜですか？」

バグのコメントにより、問題の説明を正すことができました。コードをリツールしたとき、テストにそのバグを含めることは確実でしたが、再導入しませんでした。

一般的にはあなたに同意すると言いますが、自分で挿入しないでください。

問題の開発者がバグをより意味のある方法で修正することを望んでいたので、そもそもコードについて気にする必要はありませんでした。

他のヒント

結局のところ、それは悪い習慣だと思います。バグが存在する理由を含めることをお勧めします（タイプYのfooにはプロパティZがありません）。「BugId 12345の詳細」を含めることができます。必要に応じて一緒に。

複数のレベルで統合している場合、tracのソースコードビューはBugIdに直接リンクできます。

純粋な怠。確かに、長い目で見ればもっと時間がかかりますが、短い目では "// Bug 1024";どんな努力もしません。コードが多ければ多いほど、これは悪くなります。

リビジョン12345の変更を追跡する新しいバグがあると想像してください。ログを見ると、変更が行われた理由がBug 1024であることがすぐにわかります。

その後、1024を調べて、新しい修正を行う前に、「すべてを支配するもの」を決定する前に、何を、なぜ、いつを見ることができます。

バグ番号がコミットメッセージにない場合は、コミットが修正したバグを検索する必要があります。バグは複数ある可能性があります（バグが複数回報告される場合）。

これは「ハンマーを持っている、釘でなければならない」場合だと思います。コードを管理するためのツールは、テキストエディターまたはIDEだけではありません。

履歴は、コードの外部で最適に管理されます。コードの意味は、すぐにわからない場合はコメントで説明する必要があります。

ソース管理のコミットメッセージにバグ番号を含める必要があることに同意します。

バグ番号だけを追加しないでください。 1つのバグに対して複数のチェックインを行った場合、バグ番号と件名、および修飾子を追加する必要があります。

バグ1111-64ビットシステムでFooが破壊されました。トランクへのマージ後に再び開かれたため、＃2を修正します。

一部のシステムにはバグ番号が統合されています。 mxr.mozilla.orgでは、cvsログ表示のバグ番号は自動的にbugzilla.mozilla.org番号へのリンクに変わります。コードを掘っているとき、これは大きな時間の節約になります。 Fogbugzにも同様の機能があると思います...

また、たとえシステムがそうでなくても、コメントの変更のコンテキスト全体を見たいと思わないので、多くの場合に役立ちます。これがバグトラッカーの目的です。

このようなコメントはあまり役に立たず、簡潔すぎます。

ただし、欠陥追跡システムのレコードへの参照を使用してコードをコメントすることは非常に便利で重要です（または、KMリポジトリに拡張することもできます）。

アプリケーションの動作に関する特定の問題の回避策を実装するためにコードが変更される場合があります。導入された回避策が論理的でない場合があります。他の誰かがコードを更新すると、この「悪い」コードがリファクタリングの一環として削除されることがよくあります。

コードを特定のバグ修正に属するとマークすると、リファクタリング中にコードが表示され、コードを変更する前にバグの説明を確認するよう開発者に促します。また、バグが再び開かれる状況でも役立ちます。コードの同じ部分を数回変更する必要がある場合は、代替ソリューションに時間をかけることを検討してください。

PS Joel On SoftwareのMS Officeに関するこちらの記事を参考にしてください。私が知る限り、MS OfficeとMS Windowsのコードには、長い間開発者が下した決定を説明する同様のコメントがたくさんあります。

そうでなければ間違っていると思われるコードを説明するとき、またコミットメッセージで使用するときに役立ちます。

それはしません。欠陥IDをコードに入れる理由は考えられません。代わりにリリースノート/ changelogに記載します。

自動テストの名前の一部として欠陥IDを使用すると便利だと思います：

[TestFixture]
public class Release_1_2_Bugfixes
{
  [Test]
  public void TestBug42()
  {
    Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything());
  }
}

他のプロジェクト同じことをします。

これに反対している人がどれだけいるかに驚いています。これに関する私の個人的な感覚は、これらは非常に良いアイデアだということです。バグ番号だけでなく、できれば短い要約とバグ追跡システムへのリンクを適切に含めることが望ましいという以前のコメントに同意します。

これらのコメントの利点は、歴史と以前のバグ修正が多数ある古いプロジェクトでのみ明らかです。どこにでもこれらのコメントを書く必要はありませんが、コンテキストなしでは意味をなさないかもしれないコードのブロックの前に置かれた場合、それらは非常に役立ちます。あらゆる種類の合理的に複雑なシステムでは、コンテキストなしでは非論理的または不要なコードのスニペットがあります。

システムとのやり取りまたは古い回避策のため、コードは必要です。誰かがパッチされたバグを後で再導入するのを防ぐために、コードブロックが修正するように設計されたバグを示すことが非常に役立ちます。そうしないと、コミットログに記録された理由でコミット履歴を慎重に確認している人に依存していることになります。特に、誰かがコードをリファクタリングしている場合は、ほとんどありません。

編集：特殊なコードブロックまたは追加のコンテキストが必要なコードブロックをこれらに配置することを具体的に参照しています。タイプミスを修正するたびにコメントする必要はありません。

これは、Visual Studio 2008が注釈付きで出荷されるまで行いました。古いコードを振り返って、特定のコード決定の背後に少なくとも考えがあったことをすぐに確認するのに役立ちました。

はい、以前のバージョンと比較できることはわかっていますが、マイナーなコードの更新についてすぐに気分が良くなる必要がある場合、それは非常に苦痛です。

なじみのないソースコードを閲覧していて、何か明白でないものを見つけた場合、その理由を知っておくといいでしょう。ただし、すべてのバグ修正にそのような説明が必要なわけではありません。おそらくほとんどの場合、それなしで逃げることができます。

コードの一部を見るときに誰かがバグ番号を知りたいと思う十分な理由がある場合、バグに言及するコメントを追加することは非常に素晴らしいことがあります（うまくいけば、バグの重要な部分も言い換えます、ただし）。

はい、ソース管理のコミットメッセージにはバグ番号も含まれている必要があり、リビジョンログを調べると同じ情報が得られます...しかし、コードの同じ部分が複数回変更された場合、詳細は最初のバグは引き続き適用されますが、元の変更を見つけてそのバグについて知るまでに時間がかかる場合があります。

また、あるクラスから別のクラスにコードを移動したり、ファイルの名前を変更したりする正当な理由がある場合、状況が発生します。 SVNには多くの問題がありますが、CVSには問題があります。

「関連性は非常に短命であり、コードベースを散らかす傾向がある」と頭に釘を打ちます。

ソースファイルに蓄積される無駄なクズは、少し読みにくく、保守が困難です。価値をもたらさないものはすべて削除してください。「バグ12345」現在はほとんど価値がなく、数週間後には価値がなくなります。

私たちは、多くの開発者と複数のリリースされたブランチを持つ大規模システムに取り組んでいます。

これらのバグ参照コメントは実際、あるブランチから別のブランチへの移植中に非常に役立ちます。特に、使用するSCMシステムは機能が非常に悪く、コミットコメントを取得するのが難しく、かなり古い可能性があるためです。

修正が簡単な場合、バグマーカーは必要ないかもしれません。自明でない場合は、コメントセクションに長い説明を書くよりもバグを参照する方が理にかなっている可能性があります。

この種の落書きは嫌いです。他の不快な生命体のように、彼らは時間の経過とともに蓄積し、コードベースを窒息させます。

問題は、人々が以前のバグ修正と重複するバグ修正を行ったときに本当に始まります。その後、単に間違っているか誤解を招くコードのセクションにバグ番号をラベル付けします。

このタイプのコメント IS は非常に役立ちます。バグ追跡ツールまたはソース管理ツールを変更するとどうなりますか？ BZ1722対FB3101への参照は、チェックする追跡ツール（たとえば、BugzillaまたはFogBugz）を示します。

それは良いことです！

コードを見ている人は、コードの完全な履歴を理解する可能性が低く、以前にコードのこの領域で作業したことがないため、非常に重要な変更を取り消す可能性があります。それ以外の場合は正気に見えないコードまたは同等に奇妙な顧客の要件を説明できます。

特に愚かな何かを要求する場合、アーキテクチャとコードを通じてクライアントの要件の詳細を常に把握できるとは限りません。したがって、あなたは賢明なものから始めて、あなたがそうすることを余儀なくされたときに愚かなものにコードを洗練またはハックします、バグ番号はクレイジーなコードの意図をバックアップします。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow