ソースファイルの最初のコメントにバグ番号を入れるのは良い考えですか？
ヘッダーコメント内のファイル自体にバグ番号を入れるのは良い習慣ですか？
コメントは次のようになります。
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()を直接呼び出す誘惑がないようにコードが変更されている場合は、そのコメントを削除します。コードを苛立たせて爆破するだけです。
それは完全に恐ろしい習慣です。それは純粋な複製である効果を達成するために努力を追加します。つまり、コミットログを使用するだけで追加されるのは、不整合が生じる可能性だけです。あなたのソースファイルは、あなたが決して見ないものの無制限の量で乱雑になります。
私が識別できる唯一の利点は、バージョン管理にアクセスせずにソース履歴を再構築できることです。プリントアウトを勉強するとき。しかし、バージョン管理を同時に理解できないと同時に、ソフトウェア開発の複雑さを理解するのに十分な能力を持つ人はほとんどいません。
私見では、それは非常に悪い考えです。リビジョン番号100の後、90％のコメントと10％のコードが作成されます。私はそれをクリーンで読みやすいとは考えていません。
これで私が見る唯一の点は、SCC間でコードを交換する必要があり、何らかの理由で2つのシステム間で履歴を転送できない場合です（ただし、このように履歴コメントを保存した場合でも、差分履歴が失われます）同様に、コメントを保存しても少しは役に立ちます）。
番号。
これは、バージョン管理システムを使用する前に行われたことです（つまり、ソースコードがzipファイルのバックアップであった場合）。
私は誰もがその考えに反対しており、人々がそれを行っていた歴史的理由（以前のソース管理時代）を示したと思います。
しかし、私の現在の会社では、データベース開発者がこの慣例に従っており、コードの一部にバグ番号をタグ付けしています。コードにバグがあると、この問題が発生したバグの修正をすぐに見つけることができるときに、これが役立つことがあります。私のデータベースパッケージにその情報がない場合、その実装の根本的な原因を見つけるのは容易ではありません。
はい、それはコードを散らかしますが、それはそのコードの一部がそこにある理由の発見に役立ちます。
ここで2つの問題があると思います。最初に、ほとんどのシステムでリビジョンコメントの入力が許可されているのに、なぜdiffだけに頼る必要があるのでしょうか。良いコードコメントのように、変更自体だけでなく、変更が行われた理由を発見します。
次に、この機能がある場合は、それらすべてを同じ場所に配置することをお勧めします。不要になったマークアウトされたコード行をファイルで探す必要はありません。作業コード内のコメントは、なぜこのようにコーディングされているかを説明するためにあります。
これを実践すると、形成された習慣により、誰にとってもコードベースの作業が容易になります。
関連するバグと機能の追跡、およびこのファイルを変更する理由により、履歴を深く掘り下げて差分を確認する必要があるかどうかを知ることができます。 「元の式に戻す」という要望がありました。私は改訂履歴のどこに行くべきかを正しく知っており、1つまたは2つの差分のみをレビューしました。
個人的には、リマークアウトされたコードは、試行錯誤によって解決されている問題の進行中の作業のように見えます。この混乱を本番用コードから取得します。コードの行を簡単に出し入れできるので、混乱しやすくなります。
コミットメッセージのあるVCSがなく、コメントを残すオプションのあるバグ追跡システムがない場合、それは変更を追跡するための1つのオプションであり、最適なオプションではありません。
その情報を含むスプレッドシートを用意するか、そのような「贅沢」のない環境にいる場合は、ソースの近くのどこかにテキストファイルを置いてください。
しかし、このような環境にいる場合は、VCSとバグ追跡システムへの投資に向けて訴訟を起こすことを強くお勧めします:)
いいえ、バグ修正をコード内のコメントとして追跡することはお勧めできません。これはクラッタを生成するだけです。
あなたが言及した著作権メッセージについても同じことを言います。社外の誰もこのコードを見ることがない場合は、著作権メッセージを含める理由はありません。
バージョン追跡ソフトウェア（ Git 、 [〜＃〜] svn [〜＃〜] など）を使用している場合は、コミットメッセージにそれらのメモを含める必要があります。すべてのコードファイルのヘッダーを調べて、リリースノートを生成したり、変更内容の概要を確認したりする必要はありません。これらの変更ログはすべて、バージョン追跡履歴、欠陥追跡、またはその両方に一緒に保存する必要があります。
この主題についての良い読み物を探しているなら、 Clean Code の第4章をお勧めします。
これを覚えておいてください-多くの場合、コードはそれをサポートするツールよりも長くなっています。言い換えると、課題追跡、バージョン管理、およびその他すべてのスクリプトは、開発の過程で進化します。情報が失われる。
私は同意しますが、ファイルの混乱は煩わしく、ツールを使用せずにファイルを開いてその履歴を理解することは、特にコードを保守している場合は常に非常に役立ちます。
個人的には、ツールとコード内ログの両方の余地があると思います。
私は Git がこれを実行しないことを知っています。簡単な答えは、「なぜ地球にいるのかそこに行くのか」
これは一般にモジュール化されていない設計です。このソリューションでは、ファイルはコンテンツとメタデータの間の混合になります。 Amazon S は、ファイルに追加しないファイルを保存するためのサービスのもう1つの例です [〜＃〜] yaml [〜＃〜] フロントマターなどをファイルに追加します。
ファイルのコンシューマーは、最初にバージョン管理システムを介してファイルを処理する必要があります。これは密結合です。お好みのIDEは、VCSをサポートしていないと壊れます。
このディスカッションには他にも忘れられがちな要素があると思いますが、一部の改訂コメントはチームにとって迅速です。
共有コードベースのチーム環境で作業し、複数のチームメンバーが同じコード領域で作業している可能性がある場合、変更が行われたことを示す短いリビジョンコメントを正しいスコープ（メソッドまたはクラス）に入れると、非常に役立ちます。マージまたはチェックインの競合をすばやく解決します。
同様に、複数の（機能）ブランチが関係する環境で作業する場合、第三者（ビルドマスター）が潜在的な競合を解決するために何をすべきかを特定しやすくなります。
IDEから離れてなぜ誰かが何かを変更したのかを尋ねる必要がある場合は、両方のチームメンバーの生産性に支障をきたします。適切な範囲内のクイックノートは、ほとんどを軽減または排除するのに役立ちますこの中断の。
コードの一部に直接関連付けられているバグ情報は、変更全体の整合性が逐次修正によって変更された場合は無関係になります。
コードからリリースノートを作成するために外部ツール（javadocsなど）に依存する必要がある場合、関数の概要に情報を追加するのが一般的でした。最新のバージョン管理ツールではほとんど役に立たないか冗長です。
非常にモジュール化されたコードのコメントとして意味をなすのは、将来の開発者が変更の誘惑に駆られた-背後にある理由を知らない-の回避策のようにライブラリのバグ/欠点。
私は間違いなくそのような情報をファイルの先頭に配置しません-通常、そのようなものはチケットシステムに属しています。
ただし、チケットシステムや他のドキュメントへの参照が意味をなす場合もあります。たとえば、デザインの長い説明や代替案の説明がある場合などです。または、物事をテストする方法、またはそれが正確にそのように行われた理由の説明。それが短い場合、それはファイル自体に属します。それが長い場合や大きな画像の場合は、おそらくどこか別の場所に置いて参照したいと思うでしょう。
私が現在作業に割り当てられているプロジェクトでは、すべてのファイルの先頭にこのタイプのバグ番号リストがありました。ただし、プロジェクトにまだ参加している開発者は誰も追加しません。それらのほとんどは、バージョン管理システムを使用してファイルへのバグのコミットを追跡するよりもはるかに劣るので、無駄なスペースの無駄だと考えています。
多くの修正と機能強化が行われた特定の重要なファイルでは、これらのリストが非常に大きくなり、スクロールしてコードにアクセスする必要があります。短いバグのタイトルまたは短い説明がそれぞれにリストされているため、これらのリストを確認すると、いくつかの誤検知が発生する可能性があります。
要するに、これらのリストは、せいぜい役に立たないだけでなく、最悪の場合、コードの検索と特定を困難にする、大規模で無秩序なスペースの無駄になります。