web-dev-qa-db-ja.com

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

Entity、Business Logic、Data Accessクラスの有益なクラスドキュメント形式を探しています。

私は here から次の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:
//
//==================================

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

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

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

あなたの考え、どの形式が推奨されているか、および変更履歴を書き込む標準的な方法があるかどうかを教えてください。

c#documentationcomments
15
CoderHawk

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

本当に必要なのはクラスが何のためにあるのかを示す目的セクションだけです。

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

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

27
David_001

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

Jeff Atwoodによるこの記事を読む- コメントなしのコーディング 。

14
ysolik

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

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

提示された2つの形式は、ドキュメントの生成には役に立たず、コメントのエラーが最も大きく、改訂履歴がリストされています。

5
Maniero

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

3
Martijn Verburg

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

クラスの動作を理解するために「説明」を読む必要がある場合は、（a）名前の付け方が不十分であるか、（b）動作が多すぎる不良クラス（SRP）を記述しています。

3
Chris Holmes

他の人が指摘しているように、この情報の多くはリポジトリにあり、これまで私が探していた大きなフィールドは次のとおりなので、ヘッダーテンプレートの変更に取り組んでいます。

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

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

2
rjzii

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

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

  • class documentation header（=ファイルの先頭にあるコメントブロック）には、必要な法的情報（つまり、gpl-licenceに基づくxyzによる著作権）のみが含まれています
  • クラスを使用する開発者が知っておくべきすべてのことは、class-Java-doc-comments（またはそれと同等の.net）に入力する必要があります。これにより、最新のIDEは、クラスを使用するソースコードのツールチップ情報としてこの情報を表示できます。

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

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

1
k3b