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 get
et 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.
gets or sets
ou gets
selon les accesseurs de propriété.