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


19

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.


Honnêtement, la seule chose que le commentaire me donne qui n'est pas dans le code (en supposant que c'est un membre de l'utilisateur) est que l'identifiant est unique. donc rien de tout cela n'est «nécessaire».
jk.

@Tomas - avez-vous installé le plugin GhostDoc ? il générera de bons commentaires XML pour vous si vous utilisez des bons noms de propriété pour commencer et place automatiquement le gets or setsou getsselon les accesseurs de propriété.
Trevor Pilley

@Trevor - Je l'ai installé. Je me demandais simplement si je devais changer ses modèles et supprimer les "Obtient ou définit" ou non :). C'est un excellent plugin.
Tomas

Bienvenue dans le monde de la non - documentation .
Colonel Panic

Réponses:


28

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:

entrez la description de l'image ici

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

entrez la description de l'image ici entrez la description de l'image ici entrez la description de l'image ici

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.

entrez la description de l'image ici


Merci pour une réponse complète. Je pense que ce sont malheureusement des limitations de l'IDE Visual Studio. J'y ai pensé et je pense que l'intellisense pourrait vous montrer quelles propriétés sont, par exemple, get-seulement dans le contexte actuel. Il n'est pas très pratique de plier la documentation pour l'adapter à un environnement de développement particulier. Je pense toujours que Visual Studio et C # sont si étroitement liés que cela pourrait bien être la bonne solution.
Tomas

1
@Tomas Je suis d'accord que Visual Studio devrait faire plus de distinction. Il est certainement heureux de me donner une ligne ondulée rouge la seconde où j'utilise mal la propriété.
Mike

2

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).


2

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é.


1

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.