コードコメントに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への依存度が高まるため、別のプロジェクト管理システムに移行する場合、これらのコメントはまったく意味がありません。近い将来に発生することは予測できませんが、組織コンポーネント（この場合は、コード、コードリポジトリ、プロジェクト管理システム）の結合の増加に注意を払います。
ただし、ドキュメント化された設計の決定とコードベース全体の機能のインスピレーションへの参照があることの利点はわかります。私の知る限り、メリットは
- 不慣れなコードの特定のセグメントのデバッグと強化に役立つ、設計決定への明確な道筋、
- 複数行のコメントが少ないため、コードがよりクリーンになり、新しい貢献者を脅かすことが少なくなります。
- （潜在的に）現在の技術的および非技術的利害関係者への明確な道筋
- 前述の理由により、「なぜここにあるのか」という質問の数は減少しています。
そのようなコメントは避けたいと思います。彼らにとって、あなたが特に煩わしい要件を持つ場所があると思いますが。それがなければ、誰もがコードをリファクタリングしたいと思うかもしれません。例えば。
//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とバージョンコントロールがリンクされている場合は、はいCommitメッセージに対して意味があります。
- チケットを参照すると、要求された作業に必要な変更の追跡可能性が提供されます
- この同期が可能なチケット追跡ツールは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の問題を含めることは確かにひどい習慣ではありませんが、この手法は2つの異なる懸念事項を密接に/手動で結合します（問題とコード）、そして複数のシステム/場所への更新が必要になる場合があります）（JIRA、問題が言及されているソースの任意の場所、バージョン管理履歴）。
コードのコメントは更新されないことが多いため、一般的に問題があります。
より良いアプローチは、問題追跡システムをバージョン管理システムと統合して、2つの懸念事項を別々に、自動化された方法で維持できる方法を見つけることです。
コミットコメントにJiraの問題を入力し、プラグインを使用してコミットを実際のJiraにリンクします。
コミットメッセージは次の文字で始まります：
JIRA: XBVS-1222 Fixes bugs...
たとえば、bitbucketとjiraの間のフックは、コミットをjiraにリンクします。そうすれば、たとえば、行番号を右クリックして[変更履歴を表示]を選択することで、EclipseでどのJiraが関連しているかを簡単に確認できます。 Jira課題番号とコメントが行番号列で強調表示され、マウスでホバーすると詳細が表示されます。