version-control - バグ番号コメント

Question

なぜ追加するのですか

//バグ 1024

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

score 8 · Accepted Answer

先日、私たちのコードベースでこれらの 1 つが役に立ちました。

私は、「ワークフローの後半で、なぜ彼は初期化関数をもう一度呼び出すのですか??」と言いました。

バグのコメントにより、問題の説明に進むことができました。コードを作り直したとき、そのバグをテストに必ず含め、再導入しませんでした。

私は一般的にあなたに同意すると言いますが、それらを自分で挿入しません.

問題の開発者がもっと有意義な方法でバグを修正してくれればよかったのに、そもそもコードについて疑問に思う必要がなかったからです。

score 4 · Accepted Answer

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

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

score 3 · Accepted Answer

純粋な怠惰。確かに、長期的にはより多くの時間がかかりますが、短期的には「//Bug 1024」は何の努力も必要としません。コードが多ければ多いほど、これは悪化します。

score 3 · Accepted Answer

リビジョン 12345 の変更を追跡する新しいバグがあるとします。ログを確認すると、すぐにバグ 1024 が変更が行われた理由であることがわかります。

次に、1024 を調べて、新しい修正を行う前に、何を、なぜ、いつ行うかを確認できます。これは、「すべてを支配するもの」です。

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

score 3 · Accepted Answer

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

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

ソース管理のコミットメッセージにバグ番号を記載することに同意します。

score 3 · Accepted Answer

You should never add just the bug number. You should add the bug number and the subject, and any qualifiers if you made multiple checkins for a single bug:

Bug 1111 - Foo busted on 64bit systems. Fix #2 because it was re-opened after the merge to trunk.

Some systems have bug number integration. In mxr.mozilla.org the bug number in the cvs log display is auto-magically turned into a link to the bugzilla.mozilla.org number. When you are digging in the code, this is a huge timesaver. I think that Fogbugz has a similar feature...

Also, even if your system does not, it often helps because nobody wants to see the entire context of the change in comments, that is what the bug tracker is for.

score 2 · Accepted Answer

私はそれをしません。欠陥 ID をコードに入れる正当な理由が思いつきません。代わりに、リリースノート/変更ログに記載します。

私が便利だと思うのは、自動テストの名前の一部として欠陥 ID を使用することです。

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

私は他のプロジェクトが同じことをしているのを見てきました。

score 2 · Accepted Answer

これに反対する人が多いことに驚いています。これについての私の個人的な感想は、これらは非常に良いアイデアだということです。バグ番号だけでなく、必要に応じて短い要約とバグ追跡システムへのリンクを含める必要があるという以前のコメントに同意します。

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

システムまたは古い回避策との相互作用のため、コードが必要です。誰かが後でパッチを適用したバグを再導入するのを防ぐために、できれば何らかの説明を付けて、コードブロックが修正するように設計されているバグを示すことは非常に役立ちます。それ以外の場合は、コミットログに記録された理由により、誰かがコミット履歴を注意深くチェックすることに依存しています。これは、特に誰かがコードをリファクタリングしている場合はほとんどありません。

編集:私は、これらを異常なコードブロックまたは追加のコンテキストを必要とするコードブロックに入れることについて特に言及しています。入力ミスの修正ごとにコメントするのは役に立ちませんし、コメントする必要もありません :-)

score 2 · Accepted Answer

このようなコメントはあまり役に立たず、短すぎることに同意します。

ただし、欠陥追跡システムのレコードへの参照をコードにコメントすることは非常に便利で重要です (または、所有している KM リポジトリに拡張されます)。

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

そのため、コードを特定のバグ修正に属するものとしてマークすると、リファクタリング中にそのコードが表示され、コードを変更する前にバグの説明を確認するよう開発者に促されます。また、バグが再発した場合にも役立ちます。コードの同じ部分を何度も変更する必要がある場合は、別の解決策に時間を費やすことを検討してください。

PS Joel On Software の MS Office に関するこの記事が役立つと思われるかもしれません。私が知る限り、MS Office と MS Windows のコードには、開発者が過去に行った決定を説明する同様のコメントがたくさんあります。

score 2 · Accepted Answer

間違っているように見えるコードを説明するときや、コミットメッセージで使用するときに便利です。

score 1 · Accepted Answer

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

ソースファイルに蓄積される役に立たないがらくたのすべてのビットは、それらを少し読みにくくし、維持するのを難しくします。付加価値のないものはすべて削除してください。「Bug12345」は現在ほとんど価値がなく、数週間後には価値がなくなります。

score 1 · Accepted Answer

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

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

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

score 1 · Accepted Answer

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

はい、以前のバージョンと比較できることはわかっていますが、コードのマイナーアップデートについてすぐに気分を良くしたいだけの場合、それは大変なことです。

score 1 · Accepted Answer

なじみのないソースコードを参照していて、何かわかりにくいものを見つけた場合は、その理由を知っておくと便利です。ただし、すべてのバグ修正にそのような説明が必要なわけではありません。おそらくほとんどの場合、説明がなくても済むでしょう。

score 1 · Accepted Answer

コードの一部を見たときに誰かがバグ番号を知りたいと思う十分な理由がある場合は、バグに言及するコメントを追加すると非常に便利です (ただし、バグの重要な部分も言い換えることができれば幸いです)。

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

また、あるクラスから別のクラスにコードを移動したり、ファイルの名前を変更したりする正当な理由がある場合、コードの特定のセクションの背後にある理由の根本を見つけるのがさらに難しくなる状況が発生します (名前の変更はそれほど重要ではありません)。 SVN には問題がありますが、CVS には問題があります)。

score 0 · Accepted Answer

こういう落書きは嫌いです。他の不快な生命体と同様に、それらは時間の経過とともに増加し、コードベースを窒息させます。

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

score 0 · Accepted Answer

この種のコメントは非常に役に立ちます。バグ追跡ツールやソース管理ツールを変更するとどうなるでしょうか。BZ1722 と FB3101 を参照すると、確認する追跡ツールが分かります (Bugzilla や FogBugz など)。

score 0 · Accepted Answer

それは良いことです！

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

アーキテクチャとコードを通じてクライアントの要件の詳細を常に把握できるとは限りません。したがって、賢明なものから始めて、そうしなければならないときにコードを洗練またはハッキングして愚かなものにします。バグ番号はクレイジーなコードの意図を裏付けます。

version-control - バグ番号コメント

18 に答える 18

Related

Reference