Est-ce que «Obtient ou définit ..» est nécessaire dans la documentation XML des propriétés?

Je recherche une recommandation de bonne pratique pour les commentaires XML en C #. Lorsque vous créez une propriété, il semble que la documentation XML attendue se présente sous la forme suivante:

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

Mais comme la signature de la propriété vous indique déjà quelles opérations sont disponibles pour les clients externes de la classe (dans ce cas, c'est les deux getet set), j'ai l'impression que les commentaires sont trop bavards et que peut-être ce qui suit serait suffisant:

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

Microsoft utilise le premier formulaire, il semble donc que ce soit une convention implicite. Mais je pense que le second est meilleur pour les raisons que j'ai mentionnées.

Je comprends que cette condition est un adepte d'être marqué comme n'étant pas constructif, mais la quantité de propriétés que l'on doit commenter est énorme et je pense donc que cette question a le droit d'être ici.

J'apprécierai toutes les idées ou liens vers les pratiques officielles recommandées.

La signature peut indiquer à d'autres morceaux de code quelles opérations sont disponibles; cependant, ils ne sont pas clairement montrés au codeur pendant qu'il travaille et la documentation XML est destinée aux utilisateurs et non à un compilateur.

Prenez ce cours par exemple:

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; }
}

Lorsque intellisense est tiré vers le haut pour accéder à l'une de ces propriétés, il n'y a aucune indication sur celles qui peuvent être écrites, lues à partir des deux ou les deux:

De même, lors de la visualisation de la documentation, nous ne sommes pas sûrs non plus:

En tant que tel, nous ajoutons les ensembles get ou sets , gets ou sets pour faciliter la tâche du programmeur lors de l'écriture du code. Ce ne serait certainement pas écrire un gros bloc de code qui lit et traite certaines données uniquement pour découvrir que vous ne pouvez pas réécrire ces données dans la propriété comme prévu.

StyleCop utilise la Gets or Sets ...notation qu'il applique à la règle SA1623 .

La page liée répertorie un autre cas que vous n'avez pas répertorié:

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

L'autre option que vous énumérez serait.

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

contre

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

Ce qui ne fournit aucune information sur l'indice IntelliSense que la propriété est en lecture seule, vous pouvez arriver à une convention pour ce cas aussi, mais Gets ..., Gets or Sets...fait le travail bien imo.

Il existe également d'autres variantes répertoriées dans la règle StyleCop qui sont claires en utilisant le Gets or Sets...mais ne sont pas nécessairement sans.

De plus, lors de la génération de documentation à partir de quelque chose comme Doxygen ou Sandcastle, la notation complète documenterait mieux l'API (par exemple).

La seule fois où j'ajoute des informations sur l'obtention et la définition d'une propriété dans les commentaires XML, c'est quand elle ne se comporte pas comme prévu (obtention et définition publiques directes).

Si l'un ou l'autre sont privés ou s'ils contiennent une logique supplémentaire, je les mentionne, sinon je documente simplement l'intention de la propriété.

Je serais plus heureux avec la version plus verbeuse.

L'autre, c'est comme avoir un commentaire de "compteur d'incrémentation" après, eh bien, l'incrémentation d'une variable de compteur.

Il est évident qu'il existe un Get and Set. Si vous aviez un setter privé, ce serait évident car vous auriez le mot-clé private.

Les commentaires doivent ajouter de la valeur, pas seulement être une version de commentaire de ce qu'est réellement le code.