web-dev-qa-db-ja.com

プロパティのXMLドキュメントで「取得または設定..」が必要ですか？

C＃でのXMLコメントのベストプラクティスの推奨事項を探しています。プロパティを作成すると、予期されるXMLドキュメントは次の形式のように見えます。

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

ただし、プロパティのシグネチャは、クラスの外部クライアントが使用できる操作をすでに示しているため（この場合はgetとsetの両方です）、コメントがおしゃべりすぎるように感じますそして、おそらく以下は十分でしょう：

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoftは最初の形式を使用しているため、暗黙の規則のようです。しかし、私が述べた理由から、2番目の方が良いと思います。

この質問は、建設的ではないとマークされていることを熟知していると理解していますが、コメントしなければならないプロパティの量は膨大であるため、この質問はここにある権利があると思います。

公式の推奨プラクティスへのアイデアやリンクはありがたいです。

c#.netprogramming-practicescomments
19
Tomas

署名は、他のコードに利用可能な操作を通知する場合があります。ただし、彼または彼女が働いているため、それらはコーダーには明確に示されていません。XMLドキュメントは、コンパイラーではなく、ユーザーが使用するためのものです。

このクラスを例にとります：

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

これらのプロパティの1つにアクセスするためにintellisenseがプルアップされた場合、書き込み、読み取り、またはその両方が可能なプロパティは示されません。

enter image description here

同様に、ドキュメントを表示するときも、確信が持てません。

enter image description hereenter image description hereenter image description here

そのため、getsまたはsets、gets、またはsetsを追加して、プログラマーがコードを記述しやすいようにします。確かに、一部のデータを読み取って処理し、期待どおりにそのデータをプロパティに書き戻すことができないことを確認するだけの大きなコードブロックを書くことはできません。

enter image description here

28
Mike

StyleCopは、ルール SA162 で適用されるGets or Sets ...表記を使用します。

リンク先のページには、あなたがリストしていない別のケースがリストされています。

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

あなたがリストする他のオプションは、でしょう。

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

対

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

これは、プロパティが読み取り専用であるというIntellisenseのヒントに関する情報を提供しません。この場合の規則も考えられますが、Gets ...、Gets or Sets...はimoでうまく機能します。

StyleCopルールには、Gets or Sets...を使用することで明確になる他のバリアントもリストされていますが、そうでない可能性もあります。

また、DoxygenやSandcastleのようなものからドキュメントを生成する場合、完全な表記法は（たとえば）APIをより適切にドキュメント化します。

2
NikolaiDante

プロパティの取得と設定に関する情報をXMLコメントに追加するのは、それが期待どおりに動作しない場合（ストレートパブリックgetおよびset）だけです。

どちらかがプライベートであるか、追加のロジックが含まれている場合は、それらについて言及します。それ以外の場合は、プロパティの意図を文書化します。

2
CLandry

私はもっ​​と冗長なバージョンで幸せになるでしょう。

もう1つは、カウンタ変数をインクリメントした後で「カウンタをインクリメントする」というコメントを持つようなものです。

Get and Setがあることは明らかです。プライベートセッターがある場合は、privateキーワードがあるので明らかです。

コメントは、コードの実際のコメントバージョンだけでなく、付加価値を与えるものでなければなりません。

1
ozz