問題番号でコメントするのは良い習慣ですか？

jQueryコードのコメントから多くの問題番号を見ました。（実際、jQueryコードには69の問題番号がありました。）良い習慣になると思いますが、ガイドラインを見たことはありません。

それが良い方法である場合、この方法のガイドラインは何ですか？

一般的に、私はそれを良い習慣とは思わないでしょう。しかし、例外的な場合には、非常に便利です。つまり、複雑な問題を修正するためにコードが直感的でない何かをしなければならず、説明なしに誰かがこの奇妙なコードを「修正」してそれを破りたいというリスクがあります、理由を説明すると、問題からの情報を複製する巨大なコメントになります。

関連する修正をソース管理システムにコミットするときに、コミットメッセージに問題番号を追加するだけで十分だと思います。

例えば：

バグ＃203：30秒後にデータベース接続がタイムアウトしなくなりました。

コードに変更が加えられた問題番号、開発者名、または日付を追加すると、コードベースが汚染されるだけで、ソース管理システムによって外部で実際に管理する必要があります。

ここの他のポスターにはまったく同意しません！

追跡参照を使用したコードコメントは、メンテナンスプログラミングに非常に役立ちます。

バグを追跡してコードの領域に近づいている場合、最近変更されたことがわかり、変更のコンテキストへのリンクを持っていることは神からの送信です。

はい、ソースコードを管理できますが、ファイルとモジュールを個別にチェックするのは非常に遅くなります。あなたは欲しいこれらの事は、最近の変更のためにあなたに飛び出すします。

コードベースで本当に古いものを見るので、おそらくそれらを非推奨にするでしょうが、それらを賢く使用する場合、より新しいものを保持し、開発者の時間を大幅に節約することにマイナス面はほとんどありません。

実際、バグ追跡システムへのこれらの小さな参照は、コード内の詳細なコメントよりも望ましいと思います。

「クリーンコード」のポリシーをサブスクライブする場合は、コメントを追加するのが良い方法かどうかを自問する必要があるでしょう。コードをコメントでのみ明確にすることができる場合は、コメントを追加してください。そうしないと、コードを読むだけでコードが何をするのかを簡単に理解できるはずです（変数、メソッドなどに意味のある名前を使用している場合）。

コメントが良い習慣であるかどうかについてのあなたの個人的な見解に関係なく、コメントはコメントが参照しているコードにとって直接価値のある情報を含むべきです。この場合、問題は問題番号を追加するとコードに価値が追加されるかどうかです。問題番号を追加する際に発生する問題は、いくつかの問題を満たすために大幅に変更される可能性のあるコードのセクションがあり、しばらくすると、特定の問題に関連する変更を正しく識別することができない可能性があることです。たとえば、後続の問題では、以前の問題に関連するコードを大幅にリファクタリングする必要があります。これはおそらく極端な例ですが、コード内のコメントの問題番号がどのように役に立たないかを示しています。

私が今説明した状況が決して起こらないことを保証できるなら、私はまだ問題が何であるかについての説明なしに問題番号自体はまだかなり役に立たないと主張します、そしてまだ、この情報のすべては本当にあなたに属します問題追跡システムであり、複製する必要があります。問題番号をメモするより良い場所は、バージョン管理システム内のコミットコメントです。利点は、バージョンを比較して、特定の問題に関連するコードの変更を確認できることです。一方、コードの変更の理由を確認する場合は、問題番号自体が必要な識別子を提供します。

これらすべてを念頭に置いて、コード内のコメントに問題番号を追加することは、あまり良い方法ではないことをお勧めします。

コメント自体に短い説明を加えながら、さらに読むために問題を参照することは良い習慣だと思います。

通常、コメントを追加するのは、そのコードに微妙なものや直感的でないものがある場合のみです。いくつかの微妙な問題は数行で完全に説明することができず、コメントの数十行を追加したくないので、これが達成しようとしていることを説明する短いコメントを追加し、詳細。

例えば：

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

問題123では、その攻撃がどのように見えるか、および新しいコードが攻撃に対して耐性がある理由について説明しています。

または：

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

ソースに課題番号を入力する際の主な問題は、外部参照を入手できるようになったことです。そのため、問題が失われないことを確認する必要があります。

コミットメッセージに問題番号を含めることは、ソースコードが継続的インテグレーションに結び付けられている場合に非常に役立ちます。TeamCityのようなアプリケーションはその情報を引き出し、より良いレポートを可能にします。

上記で、私はそれがコードコメントから引き出されると100％確信していないと言いました。コードに課題番号を含めることは、課題番号が保持されている場合（例：課題トラッカーを変更しない場合）、特定のプロジェクトに多くの課題がない場合に適切に機能します。

次の開発者が問題番号を調べる必要がないように、問題と解決策を説明しておけば、おそらくより役立つでしょう。コンパイラまたはミニファイヤは、コードが野生にリリースされる前にコメントを削除するだけなので、最終結果に影響はありません。