インラインコードコメントの最適なアプローチは何ですか？

20年前のレガシーコードベースにリファクタリングを行っており、同僚とコードのコメント形式（plsql、java）について議論しています。

コメントにはデフォルトの形式はありませんが、ほとんどの場合、人々はコメントで次のようなことをします。

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

私が望む将来および過去のコメントの提案された形式は次のとおりです。

// {yyyy-mm-dd}, unique_author_company_id, comment

私の同僚は、コメントだけが必要であり、過去および将来のすべてのコメントをこの形式に再フォーマットする必要があると言います。

// comment

私の議論：

• メンテナンス上の理由から、いつ、誰が変更を行ったかを知ることが重要です（この情報はSCMにあります）。
• コードは生きており、そのために歴史があります。
• 変更日付がないと、SCMツールを開いて長いオブジェクト履歴を検索しないと、変更がいつ導入されたかを知ることができないためです。
• 著者は非常に重要であるため、著者の変更は著者の変更よりも信頼できる
• 敏ility性の理由、SCMツールを開いてナビゲートする必要はありません
• 人々は、最近作成または変更されたものよりも、誰かが15年前にしたことを変更することを恐れます。
• 等

私の同僚の議論：

• 歴史はSCMにあります
• 開発者は、コード内のコードの履歴を直接認識してはなりません。
• パッケージの長さは15,000行になり、構造化されていないコメントはこれらのパッケージを理解しにくくします

最善のアプローチは何だと思いますか？または、この問題を解決するためのより良いアプローチがありますか？

一般的なコメント

私はコメントが理由（方法ではなく）であると信じています。あなたがコードに関連してコメントを維持することを何も強制していないという問題に陥る方法についてコメントを追加し始めるとき（通常、理由は変わらない（理由の説明はやがて強化されるかもしれない））。

同様に、date / authorInfoは、コードがこのように行われた理由に関して何も得られません。ツールによる強制がないため、時間の経過とともに退化する可能性があります。また、同じ情報がソース管理システムに既に保存されています（したがって、作業を複製しています（ただし、信頼性は低くなります））。

引数を調べます：

メンテナンス上の理由から、いつ、誰が変更を行ったかを知ることが重要です（この情報はSCMにあります）。

なぜ。これらのことのどちらも、コードを維持する上で重要だとは思いません。著者と話をする必要がある場合、ソース管理からこの情報を見つけるのは比較的簡単です。

そのため、コードには寿命があります。

履歴はソース管理に保存されます。
また、コメントがその人によって書かれたことを信頼しますか。Howコメントは時間とともに劣化する傾向があるため、この種の履歴は信頼できなくなります。一方、ソース管理システムは非常に正確な履歴を維持し、コメントがいつ追加/削除されたかを正確に確認できます。

変更日付がないと、SCMツールを開いて長いオブジェクト履歴を検索しないと、変更がいつ導入されたかを知ることができないためです。

コメント内のデータを信頼する場合。
この種の問題の1つは、コードに関してコメントが不正確になることです。ジョブの正しいツールに戻ります。ソース管理システムは、ユーザーの介入を必要とせずにこれを正しく行います。ソース管理システムが苦痛な場合は、それをより適切に使用する方法を学習する必要があります（その機能は通常簡単であるため）。

著者は非常に重要であるため、authorxの変更はAuthoryの変更よりも信頼できる

すべての著者（自分を除く）は、同様に信頼できます。

敏ility性の理由、SCMツールのナビゲートを開く必要はありません

あなたのソース管理ツールがあまりにも面倒な場合、誤って使用したり、（おそらく）間違ったツールセットを使用してソース管理システムにアクセスしていることになります。

人々は、15年前に誰かがしたことを変更することを恐れるでしょう。

コードが15年続いた場合、レビューを必要とせずに6か月しか続かなかったコードよりも安定している可能性が高くなります。安定したコードは安定したままである傾向があり、バグのあるコードは時間とともにより複雑になる傾向があります（バグがある理由は問題が最初に考えたほど単純ではないためです）。

ソース管理を使用して情報を取得するさらに多くの理由。

歴史はSCMにあります

はい。まだ最高の理由。

開発者はコード内のコードの履歴を直接認識してはいけません

この情報が本当に必要な場合は、ソース管理で調べます。
それ以外の場合は関係ありません。

パッケージには、15,000行の長さの構造化されていないコメントが付けられ、このパッケージは理解しにくい

コメントは、とにかく何かをしている理由を説明するものでなければなりません。
コメントは、コードがどのように機能するかを説明するものであってはなりません（アルゴリズムが明白でない限り）。

あなたの同僚を強く支持します。古いコードをコメントに残さない限り、何かが変更された理由を理解したい場合は、とにかくSCMを見ずに済ませることはできません。

コードが複雑すぎて大量のコメントを書かずに理解できない場合は、大量のコメントなしでコードを読み取り可能/保守可能にするために、リファクタリングに力を注ぐことをお勧めします。

結局のところ、ストーリーテラーではなくプログラマーを雇います;-)