web-dev-qa-db-ja.com

インラインコードコメントの最善の方法は何ですか？

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ツールを開いて長いオブジェクト履歴を検索しないと、変更がいつ導入されたかを知ることは不可能です。
  • 著者は非常に重要であるため、著者の変更は著者の変更よりも信頼できる
  • 俊敏性の理由、SCMツールを開いてナビゲートする必要がない
  • 人々は、最近作成または変更されたものよりも、15年前に誰かがしたことを変更することを恐れます。
  • 等.

私の同僚の議論：

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

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

javac#programming-practicescode-qualitycomments
13
Diego Alvarez

一般的なコメント

私は コメントは理由（方法ではない） を信じています。コードに関連してコメントが維持されることを強制するものは何もないという問題に陥る方法についてコメントを追加し始めるとき（whyは通常変更されません（理由の説明は時間の経過とともに一部強化されました）。

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

引数を検討する：

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

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

コードには歴史があるため、コードには生命があります。

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

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

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

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

すべての著者（あなた自身は別として）も同様に信頼できます。

俊敏性の理由、SCMナビゲートツールを開く必要がない

ソース管理ツールの負担が大きい場合、そのツールを誤って使用している、または（可能性が高い）ソース管理システムにアクセスするために間違ったツールセットを使用しています。

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

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

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

歴史はSCMにあります

はい。まだ一番の理由。

開発者は、コード内のコードの履歴を直接認識してはなりません。

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

パッケージは15,000行の長さで、このパッケージを理解するのが難しい構造化されていないコメントを取得します

コメントは、とにかく何かをしている理由の説明でなければなりません。
コメントは[〜＃〜]ではない[〜＃〜]コードがどのように機能するかを説明する必要があります（アルゴリズムが明確でない場合を除く） 。

32
Martin York

私はあなたの同僚を強くサポートします。古いコードをコメントに残さない限り、何かが変更された理由を理解したいのであれば、とにかくSCMを確認せずにはいられません。

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

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

6
Axel