ドキュメンテーションコメントの冗長性を避けるにはどうすればよいですか？

Question

私はちょうどStyleCopを使い始めました。私が苦労していることの1つはドキュメントの必要条件です。私はツールの有用性について議論したくありません。誰かが実際に有用なコメントを作成する方法を文書化するためのガイドラインや考え方を持っているのかどうかは不思議です。

/// <summary> 
    /// Gets a dto of personal info. 
    /// </summary> 
    /// <param name="userId"> 
    /// The id of the user. 
    /// </param> 
    /// <returns> 
    /// A dto containing personal info. 
    /// </returns> 
    public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...} 

が返す記述対要約をフレージングの標準的な方法があります：私は次のように私のコメントは、多くの場合、ちょうどStyleCopの要件を満たすために、繰り返しの多くが含まれていることを見つけますか？あなたはあなたのparamの説明に何を入れますか？ 「コメントは、実際に有用なものにする方法を文書化する。私は私のコメントは、多くの場合、ちょうどStyleCopの要件を満たすために、繰り返しの多くが含まれていることを見つける」

Answer 1

私は、要約にプロセスを記述することによって重複を避けるようにしています。パラメータでは、有効な範囲などの詳細や、ユーザーがこの情報を取得する方法を追加できます。私はまた、例えば、任意のエラー状態を一覧表示に戻り場合：

/// <summary> 
/// Gets a dto of personal info by querying the current list of users (or active directory or SQL) 
/// </summary> 
/// <param name="userId"> 
/// The id of the user. Must be greater than 0. The ID is stored in the application context or can be retrieved by a call to GetUserIdByName. 
/// </param> 
/// <returns> 
/// A dto containing personal info. Returns null if the specified user information was not found. 
/// </returns> 
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...} 

Answer 2

役に立つと冗長はお互いに何の関係もありません。

質問に「有用」は定義されていません。通常は「スタイル・コップで必要以上に大きい」という意味です。もっと何かを書く必要があると感じたら、もっと何かを書いてください。 Stylecopは最小です。あなたはそれらの最小値を超えて自由に行くことができます。

あなたのケースでは、ほとんど機能しない関数の要約を書いているからです。正式な要素（パラメーターと戻り値の型）とサマリーがお互いに繰り返すことは非常に一般的です。私はこの繰り返しが「有用な」テストにどのように失敗するのかよく分かりません。おそらく何かがある場合がなくなってあなたはそれを追加することができます。自由に拡張して書くことができます。最低限以上の「有用な」ドキュメントを書くことを止めるものはありません。

冗長性 - 面倒ではありませんが、有用ではないようです。

あなたのコメントは、インデックスとプレーンテキストページの作成を巻き起こします。形式的に構造化された部分は、索引付けと書式設定に不可欠です。

より複雑なクラス（および関数）の場合、その概要はニュアンスを拡張する場所です。たとえば、「なぜ？ 「他の制約」と「コードサンプル」とそのような種類のものがより有用になることがあります。

いつでも、と書くことができます。最小値よりです。しかし、単純な関数の場合、最小値以上の値を書くことはありません。

Answer 3

もしそれがあなたに強制されているのであれば、知的命名のような良い自己文書化技術を使っているので、何度か繰り返して苦労しなければならないかもしれません。

ドキュメントに含めることができるその他の良いものは次のとおりです。 1）書式設定 - 「500未満のすべてのユーザーがその管理者」などのようなユーザーIDに制限はありますか？これらはparamでコメントするのが良いです。

2）例外 - あなたのメソッドがそれを投げたり引っ越したりする場合は、それを使っている人がそれを処理することを知るように文書化してください。

3）サンプルコード - リターン・オブジェクトが奇数の条件のいずれかの種類になります - どのようにあなたの方法

4）特別条件を使用することを示しますか？ userIDが見つからない場合、nullまたは空白/エラーPersonalInfoDTOを返すか？

そして、冗長な情報がたくさんありますように、もちろん、簡単な方法でそれは思えるだろうが、より複雑なコードは、徹底したドキュメントから大いに恩恵を受けることができます。

Answer 4

冗長な情報であると感じたとしても、この規格を実施する理由はあります。 （つまり、 "userId - >ユーザーID"）このコメントには、そのパラメータに追加の制約がないという情報も暗黙的に含まれています。

ので、

... 
///<param name="angle"> 
///The angle in degrees. Must be below 360 and above 0. 
///</param> 
... 

あなたは、あなたがパラメータには制限がないことを述べている「のxとyの下以上でなければならない」ことを追加しない場合。

同様に、<の場合は、>タグを返します。戻り値は自明であると考えるかもしれませんが、<戻り値>タグは、エラー時にnullを返すかどうかを呼び出し元に伝えるべき場所です。または、可能な応答のリストがあっても、単一の値を返す場合。

この種の情報は非常に重要であり、stylecopは追加するだけです。

Answer 5

非常に恣意的な場所にコメントを追加するようなツールは非常に疑わしい傾向があります。

私は間違っていませんか、私はコメントの強力な支持者です。しかし、あなたの例のようなコメントは、純粋な「ノイズ」です。何も役立たず、意味のある情報があればそれは綿密に隠されています。

コメントが自動ツールによって生成される可能性がある場合、人間は最初にそれらを書き込むことはできません。他の理由（例えば、外部ドキュメントの生成）で必須の場合は、それらを生成するための自動化されたスクリプトを用意し、結果を目立たない場所に配置する必要があります。

もちろん、この関数のインターフェイスについて多くの意味があります。たとえば、パラメータの境界は何か。

Answer 6

Jayrdub：

それらのコメントのポイントはあなたのコードのドキュメントを作成することであることに留意してください。冗長性は問題ありません。これらのコメントのさまざまな部分が異なるシナリオで使用される可能性があるため、すべてのコメントが特定の状況で使用されるわけではありません。 XMLドキュメントは、MSDN形式のヘルプファイルを作成するのに便利ですが

、それはまた、Visual Studioの内のインテリセンスとツールチップで広く使われています。あなたの要約は特定の時間に表示され、あなたのparamタグは他の時間に表示され、あなたの返信タグはまだ表示されません。時にはそれらはすべて一緒に目に見え、時には見えないこともあります。要するに

、冗長性は便利です。それは、それが文書化するメソッドまたはクラスを使用しているときに、さまざまな状況でプログラマーとしてあなたに助けを提供します。

Answer 7

最悪のIMHOはプロパティです。<の値を記入することになっていますが、プロパティを説明していますが、intellisenseは<サマリーを表示します>プロパティについては、それで、あなたは同じ事を二度言ってしまいます。

私は、彼らはいくつかの本当に多くの有用な情報を提供するように簡単に要約内のプロパティ/メソッドをまとめたものが、> <のparamに詳細な説明を入れて、<値>、および<リターン>フィールドしてみてください。 （たとえば、nullとして渡すことができるかどうかなど）

私が行う第二のことは、Docのコメントを自動的に生成して自動更新するために作成したアドインを使用することです。コードを文書化する作業 - 自動化されたツールで私の詳細の大部分を記入できる場合、この「複製」情報を維持する作業を最小限に抑えます。また、コメントを自動フォーマットしてワードラップさせることで、整頓された状態に保ちます。

詳細およびダウンロードは、http://www.atomineer.com/AtomineerUtils.htmlを参照してください。

Answer 8

あなたはそれが有用なものにすることができます、私にとって

/// <summary> 
/// Gets the user's personal information. 
/// </summary> 
/// <remarks> 
/// We need this data transfer object in order to bridge Backend.SubsystemA 
/// and Backend.SubsystemB. The standard <see cref="PersonalInfo"/> won't 
/// work. 
/// </remarks> 
/// <param name="userId">Integer representing the user's ID.</param> 
/// <returns> 
/// <see cref="PersonalInfoDTO"/> representing the user, or <c>null</c> 
/// if not available. 
/// </returns> 
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...} 

summaryはハイレベル「この方法の目的は何であるか」の情報であり、remarksは、さらなる説明のためであり、あなたが作ることができる場所seeがありますあなたのドキュメントを簡単に移動することができます。それぞれの価値を追加します。

私は実際にReSharperのおかげでドキュメントのコメントが大好きです。 QuickDocコマンドをCTRL+SHIFT+Qに再マップしました。

Answer 9

Javaを実行している場合は、完全なドキュメントに注意する必要があります。ドキュメントを書くほど、実際に関連するものが見つかる可能性は低くなります。余分なマークアップを追加すると悪化します。

"指示文"をキャプチャすること、または少なくともそれらを強く強調表示することだけを考えてみてください。

私の博士号に基づいて私の詳細な返信を"tips for writing a great javadoc"に見てください。このトピックに関する研究。

Answer 10

次のような問題がある....

1. 右。誰もあなたのコメントを書くのを止めていませんが、維持することは難しくなります。コメントをコードと一致させないと、コードを読む誰かが混乱することがあります。後でコードを変更し、それらを更新する時間を忘れる/忘れてしまうことを認めてください。 ment
2. いくつかの方法はとても単純で、コメントは必要ありません。
3. 1000行を100行以上正しく読み上げるのは難しいです。はい、ビジュアルスタジオのカラーリングでも
4. あなたのコードではすべてのシングルメソッドにコメントするのに時間がかかります。
5. これらのコメントは、ライブラリを構築していても再利用できないものではなく、小さな銀色アプリケーションのようなものではありません。