コードコメントにJIRAの問題を含めることは、一般的に役立ちますか？

たまにはこういうコメントをします

# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.

または

# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.

そうすることに関する私の主な懸念は、JIRAへの依存度が高まることです。そのため、別のプロジェクト管理システムに移行する場合、これらのコメントはまったく意味がありません。近い将来に発生することは予測できませんが、組織コンポーネント（この場合は、コード、コードリポジトリ、プロジェクト管理システム）の結合の増加に引き続き注意します。

ただし、コードベース全体で、文書化された設計の決定と機能のインスピレーションへの参照があることの利点はわかります。私の知る限り、メリットは

1. 設計の決定への明確な道筋。これは、見慣れないコードの特定のセグメントのデバッグと強化に役立ちます。
2. 複数行のコメントが少ないため、コードがよりクリーンになり、新しい貢献者を脅かすことが少なくなります。
3. （潜在的に）現在の技術的および非技術的利害関係者への明確な道筋
4. 前述の理由により、「なぜここにあるのか」という質問の数は減少しています。

私はそのようなコメントを避けようとします。彼らにとって、あなたが特に煩わしい要件を持つ場所があると思いますが。それがなければ、誰もがコードをリファクタリングしたくなるかもしれません。例えば。

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

または同様にあなたはリンクを入れるかもしれません

//work around stolen from this stackoverflow answer http://stackoverflow....

しかし、カップリングの増加についてあなたが述べる理由ではありません。実際、私はすべての機能ブランチにそれらのチケットの名前を付けています。そのため、コミット履歴があっても、必要に応じてすべての作業をチケットまで追跡できます。（あなたが賢いと感じているなら、あなたはいくつかの賢い自動クローズのことをすることもできます）

いいえ、私は発券システムの変更について心配していません。しかし、私が気付いたのは、チケットが完成したら、誰もがチケットを振り返ることは非常にまれであることです。

ですからコメントはあなたの将来の取り替えに対して言っているので役に立ちます：

「いいえ、私は間違いを犯したことはありません。誰かがそれをこのようにすべきだと言ったのです。見てください！これを証明するためのチケット番号です！」

しかし、彼らは行ってそのチケットをチェックしません。人生は短すぎる。

チケット参照コメントをどこにでも置く習慣をつけると、その影響は失われます。フラグではなく「これを読んでください」は非常に重要です。彼らはただ乱雑になるだけです。

一般に、要件はテストの媒体を通じて記録する必要があります。テストに合格した場合は、要件を満たしている必要があります。テストが最初にどのように記述されたかについて心配する必要はありません。

コードコメントについては、ほとんど役に立ちません。バージョン管理コメントの場合、以下に概説する理由により非常に役立ちます。

コードのコメントは、複雑なものの意図を理解するために実際に使用する必要があります。

不正なタイプのコードコメント：

• Updated EHS 10/24/2015 -それを知りたい場合は、バージョン管理を使用して、誰がどの行を書いたかを調べます。
• For spec 0.4 -これはコミットコメントの一部になる可能性がありますが、コードを理解するのに役立ちません
• 同じタイプの他のバリエーション。

コードコメントが存在する場合は、コードブロックがビジネスドメインにどのように関連しているかを理解するのに役立ちます。

JIRAとバージョンコントロールがリンクされている場合、はい、それらはコミットメッセージに対して意味があります。

• チケットを参照すると、要求された作業に必要な変更の追跡可能性が提供されます
• JIRAはこの同期が可能な唯一のチケット追跡ツールではありません。

次のようなコメント形式を強くお勧めします。

 DIGIT-827: We only need to use the following for V4 of the computation.

JIRAおよびこの統合を備えたほぼすべてのツールは、チケット番号を認識し、解決中のチケットに関連付けるのに十分スマートです。つまり、完全なURLは必要ありません。また、特定のコミットのメリットを享受し、意味のあるコメントをすべて1行で提供できることも意味します。

JIRAでチケットを表示すると、説明などに関連するすべてのコメントを含む変更のリストが表示されます。

はい。ただし、まれなケースのみです。

一般的に、ほとんどのコードはJIRAチケットに関連して記述されると思いますので、定期的にチケットIDでコメントすることはしません。それがgit blameの目的です。しかし、場合によってはコードが直感に反する可能性があります。おそらく、コードを記述する最も明白な方法は機能せず、チケットにない理由についての議論がありました。その場合、チケット参照を含むコメントを追加することを検討します。

コードの一部で別の部分の既知のバグを回避する必要がある場合は、チケット参照を追加することも検討します。

JIRAから別のシステムに移行したい場合は、JIRAの問題をCSVとしてエクスポートして他のシステムにインポートできるため、これはJIRAに強く拘束しているとは思いません。問題IDはそのプロセス中に変更される可能性がありますが、インポートされたチケットのどこかにJIRAチケットIDを保持できるはずです。

Jiraの問題をコミットコメントに入れ、プラグインを使用してコミットを実際のJiraにリンクします。
コミットメッセージは次で始まります：

JIRA: XBVS-1222 Fixes bugs...

たとえば、bitbucketとjiraの間のフックは、コミットをjiraにリンクします。そうすれば、たとえば、行番号を右クリックして[変更履歴を表示]を選択することで、どのJiraがEclipseに関連しているかを簡単に確認できます。Jira課題番号とコメントが行番号列で強調表示され、マウスでホバーすると詳細が表示されます。

JIRAの問題をコードのコメントに含めることは確かにひどい習慣ではありませんが、この手法は2つの異なる懸念（問題とコード）を密に/手動で結合し、複数のシステム/場所（JIRA、ソース内のどこでも問題が言及されている）への更新を必要とする可能性があります。バージョン管理履歴）。

コードのコメントは更新されないことが多いため、一般的に問題があります。

より良いアプローチは、問題追跡システムをバージョン管理システムと統合して、2つの懸念事項を個別に、自動化された方法で維持できる方法を見つけることです。