ソースファイルの先頭のコメントにバグ番号を入れるのは良い考えですか?[閉まっている]


40

ヘッダーコメント内のファイル自体にバグ番号を入れるのは良い習慣ですか?

コメントは次のようになります。

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

役立つように思えますが、それは悪い習慣と見なされていますか?


23
私が尋ねる質問は、「バグデータベースではまだできない埋め込みバグ番号で何ができるか?」です。実際の使用例は考えられません。
M.ダドリー14


6
あなたがコミットメッセージ、およびそれを置く理由です@JensG logファイルにはかなり正確に同じことをお渡ししますが、ファイルを乱雑にせず...
Izkata

1
@JensGそして、特定のファイルのスコアや数百の欠陥を修正したときはどうでしょうか?...明白な答えは、あなたが定期的に古いIDをクリアということですが、その後、あなたが戻ってVCログをgrepをするある
dmckee

3
この質問は、Ars Technicaの記事の主題です。ソースファイルのヘッダーにバグをリストすべきですか?(この質問が投稿されてから15日後に公開されます)。
ピーターモーテンセン14

回答:


107

作成者が手動で、バージョン管理システムに統合されたスクリプトとトリガーによって自動で作成者、チェックインコメント、および日付情報をファイルに追加することで、これを実行したことがあります。

私は両方の方法が2つの主な理由でかなりひどいと思います。まず、特にこれらのコメントが古くなってファイルの現在の状態とは無関係になると、ファイルに混乱とノイズが追加されます。第二に、それはバージョン管理システムで既に維持されているものからの重複情報であり、変更セットをサポートする最新のバージョン管理システムを使用している場合、実際には変更に関する情報を失います。

どちらかといえば、欠陥追跡システムとの統合を検討してください。一部のツールでは、チェックインコメント内の欠陥またはタスクID番号を追跡ツールのアイテムにリンクできます。ツールにすべての欠陥、拡張要求、および作業タスクがある場合、そのようにリンクを提供できます。もちろん、これにはプロジェクトのこれらのツールへの依存という欠点が伴います。


2
「そして、変更セットをサポートする最新のバージョン管理システムを使用している場合、実際には変更に関する情報を失っています。」-詳しく説明してください。
オタク14

10
@Geek何を説明すればいいかわかりません。バグID番号を参照するファイルを調べた場合、ファイルを検索しない限り、同じ欠陥の結果として他のファイルが変更されることはありません。それが変更セットです-一緒にチェックインされたファイルのコレクションです。
トーマスオーエンズ

9
また、新しいバグ追跡システムに移行すると、それらの数値はすべて即座に役に立たなくなります。私の現在の仕事では、10年も使われていなかったバグ追跡ソフトウェアからのコメントが含まれているコメントに出くわしました。
14年

2
そのため、新しいバグ追跡システムに変更した後、それらは存在しないかのように有用になります。しかし、ある時点で何らかの値を提供し、現在は負の値を提供していないと仮定して、なぜそうしないのですか?
たけ

@ 17of26 –「古い問題追跡バグ1234」のようなコメント以外のメカニズムがなければ、古いバグ/問題を新しいものにリンクできると思います。
ケニーエビット14

42

私がこれを行うケースは1つだけです。つまり、将来のプログラマーに対する警告の一部として、「foo()ここで関数を直接呼び出さないでください。これにより、バグ#1234、つまり...が発生します」、バグが続きます。

また、foo()直接呼び出したい誘惑がないようにコードが変更された場合は、そのコメントを削除してください。コードをいらいらさせ、爆発させるだけです。


19
たぶん私はややこしいかもしれfoo()ませんが、直接呼び出されてはならない場合は、コードを不可能な方法で構造化する必要があります。
メタファイト

20
ああ、私はテキストをより具体的にするために、例として何かを書き込もうとしました-文字通りに私を連れて行かないでください。より良いケースは、外部ライブラリを使用し、特定の目的で通常使用する関数にバグがあった場合です。次に、「foo()ここに電話しないでください」というコメントが妥当です。
レム14

16

それはまったく恐ろしい習慣です。それは純粋な複製である効果を達成するために努力を追加します。つまり、コミットログを使用するだけで追加されるのは、不整合が生じる可能性があるということです。ソースファイルには、見たこともないほどの量のものが散らばっています。

私がまったく識別できる唯一の利点は、バージョン管理にアクセスせずに、たとえば印刷物を勉強するときなど、ソース履歴を再構築できることです。しかし、ソフトウェア開発の複雑さを十分に理解でき、同時にバージョン管理を理解できない人はほとんどいません。


1つのファイルでいくつのバグが発生する可能性があり、その数がある場合はおそらく書き換えの時間です。
アンディ14

11

いや

これは、バージョン管理システムを使用する前(つまり、ソースコードがzipファイルの単なるバックアップであったとき)に人々がしたことです。


2
これは、ある種のバージョン管理システムでした(そして、2006年と同じくらい前にソフトウェアハウスで運用されていましたが、今日どこかで使用されていることは間違いありません)。
ジュウェンティング

1
@jwentingまさにこのサイトで、現在それが現在行われている店舗で働いている不幸な人々からの質問を見ました:
Carson63000 14

優れたソース管理システムを使用しています。コードをチェックインするとき、私以外はコメントを入れません。<shrug>特定のことをコメントします(SCMによって常に追跡されるとは限らないPLSQLなど)。説明のためにコードをコメントしますが、特定のバグに結び付けることはありませんが、チェックインするときは常にSCMコミットコメントのバグを参照します。
知識をひけらかす

11

それは、私見、非常に悪い考えです。リビジョン番号100の後、90%のコメントと10%のコードができます。私はそれをきれいで読みやすいとは考えません。

私が見る唯一のポイントは、SCC間でコードを交換する必要があり、何らかの理由で2つのシステム間で履歴を転送できない場合です(ただし、履歴コメントをそのように保存しても、diff履歴は失われます)同様に、コメントを保存しても少ししか役に立ちません)。


8

私は誰もがこの考えに反対しており、人々がそれを行っていた理由の歴史的な理由(ソース管理前の時代)を示したと思います。

しかし、私の現在の会社では、データベース開発者はこの慣行に従っており、さらにコードの一部にバグ番号をタグ付けしています。コードにバグがあり、この問題を引き起こしたバグ修正をすぐに見つけることができる場合、これが役立つことがあります。データベースパッケージにその情報がない場合、その実装の根本原因を見つけるのは簡単ではありません。

はい、それはコードを乱雑にしますが、そのコードがそこにある理由の理由を見つけるのに役立ちます。


3
絶対に。プログラマーは冗長性に恐怖を感じているため、同じ方法でさまざまな方法でアクセスできるのを避けていると感じることがあります。プログラマーは通常、パフォーマンスの低下に恐怖を感じているため、プログラムでキャッシュを使用するため、これは非常に興味深いものです。しかし、バグ番号が最も役立つ場所の隣のコードにバグ番号をキャッシュすることは悪いと考えられますか?うーん
JensG 14

多くの場合、その情報を取得する別の方法があります(私が取り組んでいるプロジェクトright click > Team > Show Annotationsでは、現在のファイルのgitの非難を取得することでしょう)が、違いは、コメントが発見可能性があることです-彼らはあなたに飛び出すことができます-そしてアノテーションを使用すると、意識的にそれらを探しに行く必要があります。
デビッドコンラッド14

考え、決定し、クリックし、クリックし、クリックし、スクロールします。それが私が「コードのキャッシング」と言った理由です。そこにあるなら、私はそれを見ます。
JensG 14

2
@JensG興味深い視点。キャッシュはパフォーマンスを改善できますが、キャリングコストもかかります。冗長な人間の努力によってキャッシュを充填、更新、無効化、フラッシュなどする必要がある場合、特にこのような非正規化された構造の同期がいかにひどい人間であるかを考えると、費用便益比に疑問を呈します。
ジェフリーハンティン14

7

ジョエルテストのポイントの1つは

バグデータベースはありますか?

これらの情報は、重要だと思われる場合はバグデータベースに保存されている可能性がありますが、コメントのノイズにすぎません。


1
問題の例を参照してください-コメントはバグデータベースを参照します...
Izkata

@Izkataしかし、それがポイントです。データベース自体には、コメント付きの「コメント」フィールドがある場合があります。問題は、バグデータベースがあるかどうかではなく、それをソースファイルに保存することをお勧めします。コメントであっても、データベース自体に保持する必要があると思います。なぜなら、それが目的だからです。
ピエールアラード14

6

ここには2つの問題があると思います。まず、ほとんどのシステムでリビジョンコメントの入力が許可されているのに、なぜdiffのみに依存する必要があるのでしょうか?適切なコードコメントのように、変更自体だけでなく、なぜ変更が行われたのかがわかります。

次に、この機能がある場合は、すべてを同じ場所に配置することをお勧めします。不要になったコード行をマークアウトするためにファイルを調べる必要はありません。作業コード内のコメントは、このようにコーディングされている理由を説明するためにあります。

これを実践すると、形成された習慣により、コードベースが誰にとっても作業しやすくなります。

関連するバグと機能の追跡、およびこのファイルを変更する理由は、履歴を掘り下げて差分を確認する必要がある程度を知ることができます。「元の式に戻す」というリクエストがありました。改訂履歴内の正しい場所を知っていて、1つまたは2つの差分のみを確認しました。

個人的には、コメントアウトされたコードは、試行錯誤によって解決されている問題の進行中の作業のように見えます。量産コードからこの混乱を取り除いてください。コードの行を簡単に入れたり出したりできるので、混乱しやすくなります。


2

コミットメッセージのあるVCSがなく、コメントを残すオプションのあるバグ追跡システムがない場合、変更を追跡するのは最適なオプションではなく、1つのオプションです。
その情報が記載されたスプレッドシートを用意するか、そのような「贅沢」のない環境にいる場合は、ソースの近くにテキストファイルを置いてください。
しかし、あなたがそのような環境にいるなら、VCSとバグ追跡システムへの投資に向けてケースを構築し始めることを強くお勧めします:)


2

これを覚えておいてください-コードは多くの場合、それをサポートするツールよりも長くなります。別の言い方をすれば、課題追跡システム、バージョン管理、および他のすべてのスクリプトは、開発の過程で進化します。情報が失われます。

私は同意しますが、ファイルの乱雑さは煩わしく、ツールを使用せずにファイルを開いてその履歴を理解することは、常に非常に役に立ちました-特にコードを保守している場合。

個人的には、ツールとコード内ログの両方に余裕があると思います。


2

私が知っているGitがこれを行わないと、単純な答えは、「地球上で、なぜだろう、それはそこに行きます?」

一般に、モジュール性の低い設計です。このソリューションでは、現在、ファイルはコンテンツとメタデータの間で混在しています。Amazon S3は、ファイルにYAMLフロントマターなどを追加しないファイルを保存するサービスの別の例です。

ファイルのコンシューマーは、最初にバージョン管理システムを介して処理する必要があります。これは密結合です。たとえば、VCSをサポートしていない場合、お気に入りのIDEが壊れます。


2

いいえ、バグ修正をコード内のコメントとして追跡することはお勧めできません。これは混乱を生むだけです。

あなたが言及した著作権メッセージについても同じことを言います。社外の誰もこのコードを見ない場合、著作権メッセージを含める理由はありません。

バージョン追跡ソフトウェア(GitSVNなど)を使用している場合は、コミットメッセージにそれらのメモを含める必要があります。すべてのコードファイルのヘッダーを掘り下げてリリースノートを生成したり、行われた変更の概要を確認したりする人はいません。これらの変更ログはすべて、バージョントラッキング履歴、欠陥トラッカー、またはその両方にまとめて保存する必要があります。

このテーマについての良い読み物を探しているなら、Clean Codeの第4章をお勧めします


著作権表示もあり、ファイルが雇用主のものであることを従業員に通知します(わずかに冗長)。そしておそらく、著作権通知ある場合にのみ適用されると考える人の数によって判断して、違法な共有を(従業員によるものでさえ)阻止するでしょう。
ベルントジェンドリセック14

1

この議論には、しばしば忘れられがちですが、改訂コメントがチームにとって迅速なケースである他の要素があると思います。

共有コードベースのチーム環境で作業し、複数のチームメンバーがコードの同じ領域で作業している可能性がある場合、変更が行われたことを示す正しいスコープ(メソッドまたはクラス)に短い改訂コメントを入れると非常に便利です。マージまたはチェックインの競合をすばやく解決します。

同様に、複数の(機能)ブランチが関係する環境で作業する場合、第三者(ビルドマスター)が潜在的な競合を解決するために何をすべきかを簡単に識別できます。

IDEから離れて、なぜ彼らが何かを変更したのかを誰かに尋ねなければならないときはいつでも、それは両方のチームメンバーの生産性を破壊します。適切な範囲内の簡単なメモは、この中断のほとんどを軽減または排除するのに役立ちます。


3
質問は右の著作権メッセージの後に、ソースファイルの先頭にコメントについてです-これは、より狭いスコープのコメントとは何の関係もありません
ブヨ

ただし、ここでのすべての答えは、まさにそれについて語っています。クラスファイル全体に大幅な変更を加えた場合(再編成またはフォーマットの修正)、クラスファイルをスコープとしてコメントしませんか?
StingyJack 14

0

コードの一部に直接関連付けられているバグ情報は、変更全体の整合性が次の修正によって変更されると無関係になります。

コードからリリースノートを作成するために外部ツール(javadocsなど)に依存しなければならなかったときに、関数の概要に情報を追加するのが一般的でした。最新のバージョン管理ツールではほとんど役に立たないか冗長です。

将来の開発者がその背後にある理由を知らずに-の回避策のように変更しようとする不明瞭または非恒星のコーディングに頼らなければならない場合、非常にモジュール化されたコードのコメントとしてのみ意味がありますライブラリのバグ/欠点。


0

私は間違いなく、ファイルの先頭にそのような情報を入れません-通常、そのようなことはチケットシステムに属します。

ただし、チケットシステムやその他のドキュメントへの参照が意味をなす場合があります。たとえば、デザインの説明が長い場合や、代替案の説明がある場合。または、物事をテストする方法、またはそれがまさにそのように行われた理由の説明。それが短い場合、ファイル自体に属します。それが長く、および/またはより大きな画像についてのものである場合は、おそらくそれを別の場所に置いて参照したいと思うでしょう。


これは、既に前の回答に投稿されたものに相当な価値を付加していないようだ
ブヨ

0

現在仕事で割り当てられているプロジェクトには、すべてのファイルの先頭にこのタイプのバグ番号リストがありました。ただし、プロジェクトにまだ残っている開発者は誰もいません。彼らの多くは、バージョン管理システムを使用してファイルへのバグコミットを追跡するよりもはるかに劣っているため、無駄なスペースの無駄だと考えています。

多くの修正と機能強化が行われた特定の重要なファイルでは、これらのリストが非常に大きくなったため、コードに到達するためにスクロールする必要があります。これらのリストをグレーピングすると、短いバグタイトルまたは短い説明がそれぞれリストされるため、いくつかの誤検知が発生する可能性があります。

要するに、これらのリストはせいぜい役に立たず、最悪の場合、コードの検索や特定を困難にする大規模で混chaとしたスペースの無駄です。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.