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

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

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

 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

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

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

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

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

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

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

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

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

いや

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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