クラスのドキュメントヘッダーに何を含める必要がありますか

エンティティ、ビジネスロジック、およびデータアクセスクラスの有益なクラスドキュメント形式を探しています。

ここから次の2つの形式が見つかりました

フォーマット1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

フォーマット2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

以下は基本的な要素だと思います

• 著者
• 作成日
• 説明
• 改訂履歴

とにかく名前空間とクラス名があるので。

あなたの考え、どの形式が推奨されているか、改訂履歴を書く標準的な方法があるかどうかを教えてください。

あなたが提案した情報のほとんどは、ソースリポジトリにあります。

本当に必要なのは、目的のセクションだけです。このセクションには、クラスの目的が示されています。

他の情報を知りたいと思うたびにリポジトリを見るのは面倒でしょうか？私はノーと言います。原作者が誰であるかをどれくらいの頻度で気にしますか？または、ファイルが最初に作成されたとき？プラグイン（Visual StudioのAnkh SVNなど）を使用すると、現在のファイル内で右クリックしてファイルのリポジトリログを表示できるため、この情報を実際に見るのはそれほど面倒ではありません。

さらに、バージョン履歴をコメントに保存する場合、このコメントを維持する必要があります。だから、時間が経つにつれて、あなたに嘘をつく可能性があります。ソースコードリポジトリはこの履歴データを自動的に保持するため、そのメンテナンスは不要であり、正確です。

説明的なクラス、メソッド、および変数名を持ちます。これにより、目的や説明などのコメントが不要になります。メソッド名が短いほど良いと思うこともあります。それどころか、目的が明確に記述されている限り、必要なだけメソッド名を作成してください。絶対に不可欠なメモのみを持ち、特定の方法でコードを理解するのに役立ちます。コードを変更するとき、プログラマーはコメントの更新を忘れることがよくあります。コメントとコードが同期しなくなり、善よりも害を及ぼすことになります。

コメントなしのジェフアトウッドコーディングによるこの記事を読んでください。

標準タグを使用してドキュメントを生成します。これ以上でもそれ以下でもありません。こちらをご覧ください

クラスに属さない情報は決して入れません。作成者、データ、リビジョンは、バージョン管理システムに保存するデータです。

提示された2つの形式は、ドキュメントの生成には役に立たず、コメントに最大の誤りがあり、改訂履歴をリストします。

この情報の多くはソース管理リポジトリによって追加でき、クラスのスコープと動作を正確に記述する必要があるのは説明だけです。例として、Java JDKのJavadocをいくつか見ることをお勧めします。

そのリストのすべては不要です。ソース管理はほぼすべてを処理する必要があり、カバーしていないものは適切な命名規則によって処理されます。

クラスが何をしているのかを理解するために「説明」を読む必要がある場合、（a）名前の付け方が悪いか、（b）あまりにも多くの悪いクラスを書いた（SRP）のいずれかです。

他の人が指摘しているように、この情報の多くはリポジトリにあり、これまで私が探していた大きなフィールドは次のとおりです。

• 説明 -コードによって行われていること。
• 注 -コード自体のコメントから簡単に導き出せないコードについて知っておく必要があるもの。
• 参照 -コードが依存する参照は、使用includeまたは類似のステートメントを介して明確にされていません。

含めると便利な項目の1つは、キーワードのセクションです。関数、クラス、構造体などの名前を検索できる場合がありますが、ファイル内の他の名前では明確にならないキーワードもあります。または、古くて文書化が不十分なコードの場合、保守のためにコードを文書化する最初のステップになるかもしれません。

私がこれまで読んだ他の回答のほとんどは、常に利用可能なリポジトリが1つしかないことを前提としていました

ソースコードはリポジトリへの接続を失う可能性があるため（つまりコピーされる場合）、私のクラスのドキュメントは次のようになります。

• class documentation header （=ファイルの先頭にあるコメントブロック）には、必要な法的情報のみが含まれています（gpl-licenceでのxyzによる著作権）
• クラスを使用する開発者が知っておくべきことはすべて、class-java-doc-comments（または.netに相当するもの）に移動して、現代のide-sがこの情報をクラスを使用するソースコードのツールチップ情報として表示できるようにする必要があります

また、バグ修正または機能リクエストのチケット番号を追加して、クラスが作成された場所/時期/理由を知ることができます（幸運にも数年後でもチケットにアクセスできる場合）。

ビーイングが古いクローズドソースのレガシープログラムの問題を修正するように頼んだとき、コードの元の要件を理解するのに非常に貴重なチケット番号。