私たちのショップの上級開発者は、コードが変更されるたびに、責任のあるプログラマーが自分が何をしたかを示すインラインコメントを追加する必要があると主張しています。これらのコメントは通常次のようになります// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

リビジョン管理にはTFSを使用しますが、この種のコメントは、インラインノイズよりもチェックインメモとしてはるかに適切であると思われます。TFSでは、チェックインを1つ以上のバグに関連付けることもできます。古い、よく変更されるクラスファイルの一部は、コメントとLOCの比率が1：1に近いように見えます。私の目には、これらのコメントによりコードの読み取りとゼロ値の追加が難しくなります。

これは他のショップでの標準的な（または少なくとも一般的な）慣行ですか？

私は通常、このようなコメントは悪い習慣だと考えており、この種の情報はSCMコミットログに属していると思います。ほとんどの場合、コードが読みにくくなります。

ただし、特定の種類の編集では、このようなことを頻繁に行います。

ケース1-タスク

Eclipse、Netbeans、Visual StudioなどのIDEを使用する（または他のコードベースでテキスト検索を行う何らかの方法がある）場合、チームは特定の「コメントタグ」または「タスクタグ」を使用する可能性があります。その場合、これは便利です。

コードを確認するときに、次のようなものを時々追加します。

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

または：

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

コミットログに何かを含めることは良いことですが、バグ修正XYが完全に忘れられた理由をレビューミーティングで尋ねるときには十分ではないため、Eclipseでこれをタスクビューで見ることができるさまざまなカスタムタスクタグを使用しますそしてすり抜けた。したがって、緊急の問題や本当に疑わしいコードの部分では、これは追加のリマインダーとして機能します（ただし、通常はコメントを短くしてコミットログを確認します。これはリマインダーがここにあるので、コードも混乱しないずっと）。

ケース2-サードパーティのライブラリのパッチ

何らかの理由でパッチを適用する必要があるため、製品がソース（またはライブラリであるがソースから再構築）としてサードパーティのコードをパッケージ化する必要がある場合、それらの「警告」をリストする別のドキュメントにパッチを文書化します将来の参照のために、ソースコードには通常、次のようなコメントが含まれます。

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

ケース3-明白でない修正

これはもう少し議論の余地があり、上級開発者が求めているものに近いものです。

私が現在取り組んでいる製品では、時々（間違いなく一般的なことではありませんが）次のようなコメントがあります。

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

これは、バグ修正が非自明であり、コードが異常な場合にのみ行います。これは、たとえばブラウザの奇抜なケースの場合や、製品にドキュメントのバグがあるために実装する必要があるCSS修正があいまいな場合などです。したがって、一般的には内部問題リポジトリにリンクします。このリポジトリには、バグ修正の背後にある詳細な理由と、外部製品のバグのドキュメントへのポインタが含まれます（たとえば、Internet Explorer 6の既知の欠陥のセキュリティ勧告、またはそんな感じ）。

しかし、言及したように、それは非常にまれです。タスクタグのおかげで、これらを定期的に実行して、これらの奇妙な修正がまだ意味をなすか、段階的に廃止できるかどうかを確認できます（たとえば、最初にバグを引き起こしたバグのある製品のサポートを削除した場合）。

これだけで：実際の例

場合によっては、何もないよりはましです:)

コードベースで巨大な統計計算クラスに出会いました。ヘッダーコメントは、通常のyaddaやyadda（レビュアー、日付、バグID）を含む変更ログの形式でした。

最初は廃棄することを考えていましたが、バグIDは現在の課題トラッカーの規則と一致しないだけでなく、入社前に使用されていたトラッカーのいずれとも一致しませんでした。そのため、コードを読み通して、クラスが何をしていたか（統計学者ではない）を理解しようとし、これらの欠陥レポートを掘り下げようとしました。偶然にも、それらはかなり重要であり、それらを知らないうちにファイルを編集する次の人の生活を受け入れていたでしょう。 。結論として、これらがそこになかったら、私は知らなかっただろう。彼らがそこにいなかったなら、そして私はクラスをよりよく理解していたなら、

これらのような非常に古い要件を追跡するのが難しい場合があります。結局、私がしたことはまだヘッダーを削除することでしたが、これらの「奇妙な」計算が特定の要求である理由を説明する各犯罪関数の前にブロックコメントを忍び込ませました。

だからその場合、私はまだこれらを悪い習慣だと考えましたが、少年は元の開発者が少なくともそれらを入れてくれて幸せでした！代わりにコードを明確にコメントする方が良かったのですが、それは何もないよりはましだったと思います。

バージョン管理下にないファイルにはこの方法を使用します。メインフレームで実行されるRPGプログラムがあり、それらをバックアップするよりもはるかに多くのことを行うことが難しいことが証明されています。

バージョン管理されたソースコードについては、チェックインノートを使用します。私はそれが彼らが属する場所であり、コードを乱雑にしないと思います。結局のところ、メタデータです。

私たちは昔、SWショップでこのプラクティスを実施していました。マネージャーは、紙の上でコードファイルを読み取り、改訂履歴を追跡できるようにしたいと主張しました。言うまでもなく、彼が実際にソースファイルの印刷物を見た具体的な機会は覚えていません：-/

幸運なことに、その後の私のマネージャーは、バージョン管理システムで何ができるかについてより知識が豊富でした（その最初のショップでSourceSafeを使用したことを追加する必要があります）。したがって、バージョン管理メタデータをコードに追加しません。

通常、SCMおよびIDEで「注釈を表示」（Eclipseではこれと呼ばれる）機能を使用できる場合、コードの一部が変更されたコミットを簡単に確認でき、コミットのコメントで誰と理由がわかる必要はありません。

このようなコメントをコードに入れたのは、それが将来混乱を引き起こす可能性のある特に奇妙なコードである場合、バグ番号を簡単にコメントしてバグレポートにアクセスして読むことですそれについての詳細。

明らかに、そのようなコメントは時間の経過とともに不正確であることがほぼ保証されます。行を2回編集する場合、2つのコメントを追加しますか？彼らはどこに行きますか？したがって、より良いプロセスはツールに依存することです。

これは、何らかの理由で上級開発者が変更を追跡し、変更を問題追跡システムに接続するための新しいプロセスに頼ることができないことを示しています。競合を解決するには、この不快感に対処する必要があります。

彼がそれに頼ることができない理由を理解する必要があります。古い習慣ですか？SCMシステムの悪い経験？彼にとってうまくいかないプレゼンテーション形式？たぶん彼は、「git blame」やPerforceのタイムラインビュー（本質的にはこれを示していますが、どの問題が変更をトリガーしたかを示していない場合があります）などのツールについても知りません。

彼の要件の理由を理解しないと、彼を説得することはできません。

私は20歳以上のWindows製品に取り組んでいます。私たちには、長い間実施されている同様のプラクティスがあります。この習慣が私のベーコンを救った回数を数えることはできません。

いくつかのものが冗長であることに同意します。以前は、開発者がこのプラクティスを使用してコードをコメントアウトしていました。これを確認したら、先に進んでコードを削除するように伝えますが、コメントは不要です。

しかし、多くの場合、10年ほど前に20人の開発者によって修正されたがリファクタリングされていないコードを見ることができます。誰もが元のコードにあった要件の詳細をすべて忘れてしまい、すべての変更を気にせず、信頼できるドキュメントもありません。

欠陥番号付きのコメントは、コードの起源を調べるための場所を提供します。

そのため、SCMシステムは多くのことを行いますが、すべてではありません。これらを他のコメントと同様に扱い、重要な変更が行われた場合はいつでも追加してください。あなたのコードを見ている開発者は、どのように感謝していますか？

VCSがある場合、コメントのすべての変更について言及しても意味がありません。特定の行に関連する特定のバグやその他の重要な注意事項に言及すると便利です。変更には、同じコミットメッセージの下に、多くの変更された行が含まれる場合があります。

わかりません。

作業中にコード内でTODOをスプラッターします。目標は、レビュー時間までにTODOを削除することです。