Les commentaires XML sont-ils une documentation nécessaire?

J'étais un fan d'exiger des commentaires XML pour la documentation. J'ai depuis changé d'avis pour deux raisons principales:

1. Comme un bon code, les méthodes doivent être explicites.
2. En pratique, la plupart des commentaires XML sont des bruits inutiles qui n'apportent aucune valeur supplémentaire.

Plusieurs fois, nous utilisons simplement GhostDoc pour générer des commentaires génériques, et c'est ce que j'entends par bruit inutile:

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

Pour moi, c'est évident. Cela dit, s'il y avait des instructions spéciales à inclure, nous devrions absolument utiliser des commentaires XML.

J'aime cet extrait de cet article :

Parfois, vous devrez écrire des commentaires. Mais ce devrait être l'exception et non la règle. Les commentaires ne doivent être utilisés que lorsqu'ils expriment quelque chose qui ne peut pas être exprimé en code. Si vous voulez écrire du code élégant, efforcez-vous d'éliminer les commentaires et écrivez plutôt du code auto-documenté.

Ai-je tort de penser que nous ne devrions utiliser les commentaires XML que lorsque le code n'est pas suffisant pour s'expliquer par lui-même?

Je pense que c'est un bon exemple où les commentaires XML rendent le joli code laid. Il faut un cours comme celui-ci ...

public class RawMaterialLabel : EntityBase
{
    public long     Id                      { get; set; }
    public string   ManufacturerId          { get; set; }
    public string   PartNumber              { get; set; }
    public string   Quantity                { get; set; }
    public string   UnitOfMeasure           { get; set; }
    public string   LotNumber               { get; set; }
    public string   SublotNumber            { get; set; }
    public int      LabelSerialNumber       { get; set; }
    public string   PurchaseOrderNumber     { get; set; }
    public string   PurchaseOrderLineNumber { get; set; }
    public DateTime ManufacturingDate       { get; set; }
    public string   LastModifiedUser        { get; set; }
    public DateTime LastModifiedTime        { get; set; }
    public Binary   VersionNumber           { get; set; }

    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

... Et le transforme en ceci:

/// <summary>
/// Container for properties of a raw material label
/// </summary>
public class RawMaterialLabel : EntityBase
{
    /// <summary>
    /// Gets or sets the id.
    /// </summary>
    /// <value>
    /// The id.
    /// </value>
    public long Id { get; set; }

    /// <summary>
    /// Gets or sets the manufacturer id.
    /// </summary>
    /// <value>
    /// The manufacturer id.
    /// </value>
    public string ManufacturerId { get; set; }

    /// <summary>
    /// Gets or sets the part number.
    /// </summary>
    /// <value>
    /// The part number.
    /// </value>
    public string PartNumber { get; set; }

    /// <summary>
    /// Gets or sets the quantity.
    /// </summary>
    /// <value>
    /// The quantity.
    /// </value>
    public string Quantity { get; set; }

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

    /// <summary>
    /// Gets or sets the lot number.
    /// </summary>
    /// <value>
    /// The lot number.
    /// </value>
    public string LotNumber { get; set; }

    /// <summary>
    /// Gets or sets the sublot number.
    /// </summary>
    /// <value>
    /// The sublot number.
    /// </value>
    public string SublotNumber { get; set; }

    /// <summary>
    /// Gets or sets the label serial number.
    /// </summary>
    /// <value>
    /// The label serial number.
    /// </value>
    public int LabelSerialNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order number.
    /// </summary>
    /// <value>
    /// The purchase order number.
    /// </value>
    public string PurchaseOrderNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order line number.
    /// </summary>
    /// <value>
    /// The purchase order line number.
    /// </value>
    public string PurchaseOrderLineNumber { get; set; }

    /// <summary>
    /// Gets or sets the manufacturing date.
    /// </summary>
    /// <value>
    /// The manufacturing date.
    /// </value>
    public DateTime ManufacturingDate { get; set; }

    /// <summary>
    /// Gets or sets the last modified user.
    /// </summary>
    /// <value>
    /// The last modified user.
    /// </value>
    public string LastModifiedUser { get; set; }

    /// <summary>
    /// Gets or sets the last modified time.
    /// </summary>
    /// <value>
    /// The last modified time.
    /// </value>
    public DateTime LastModifiedTime { get; set; }

    /// <summary>
    /// Gets or sets the version number.
    /// </summary>
    /// <value>
    /// The version number.
    /// </value>
    public Binary VersionNumber { get; set; }

    /// <summary>
    /// Gets the lot equipment scans.
    /// </summary>
    /// <value>
    /// The lot equipment scans.
    /// </value>
    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

Si vos commentaires ne ressemblent qu'à ceci:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Alors oui, ils ne sont pas du tout utiles. S'ils lisent quelque chose comme ça:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Alors je dirais qu'ils ont de la valeur. Donc pour répondre à votre question: des commentaires sont nécessaires quand ils disent quelque chose que le code ne dit pas.

Une exception: il est bon d'avoir des commentaires sur tout ce qui est accessible au public si vous écrivez une bibliothèque / API qui sera accessible au public. Je déteste utiliser une bibliothèque et voir une fonction nommée getAPCDGFSocket()sans explication de ce qu'est un APCDGFSocket (je serais heureux avec quelque chose d'aussi simple que This gets the Async Process Coordinator Data Generator File Socket). Donc, dans ce cas, je dirais d'utiliser un outil pour générer tous les commentaires, puis de modifier manuellement ceux qui en ont besoin (et assurez-vous que vos acronymes cryptiques sont expliqués).

De plus, les getters / setters sont généralement de mauvais exemples pour "les commentaires sont-ils nécessaires?" car ils sont généralement assez évidents et les commentaires ne sont pas nécessaires. Les commentaires sont plus importants sur les fonctions qui exécutent un algorithme où une explication des raisons pour lesquelles les choses sont faites de cette façon pourrait rendre le code beaucoup plus compréhensible et faciliter le travail des futurs programmeurs.

... et enfin, je suis presque sûr que cette question est pertinente pour tous les styles de commentaires, pas seulement ceux qui sont formatés en XML (que vous utilisez parce que vous travaillez dans un environnement .NET).

Les commentaires qui semblent inutiles aux utilisateurs qui peuvent lire le code deviennent plutôt utiles aux utilisateurs qui n'ont pas accès à la source. Cela se produit lorsque la classe est utilisée comme API externe par des personnes extérieures à votre organisation: les codes HTML générés à partir de vos documents XML sont leur seul moyen d'en savoir plus sur vos classes.

Cela dit, un commentaire qui réitère le nom de la méthode avec des espaces ajoutés entre les mots reste inutile. Si votre classe doit être utilisée en dehors de votre organisation, vous devez documenter au moins les plages valides pour vos valeurs. Par exemple, vous devez dire que la définition UnitOfMeasurede nullest illégale, que la valeur fournie au setter ne doit pas contenir d'espaces au début ou à la fin de la chaîne, etc. Vous devez également documenter la plage de LabelSerialNumbersi elle diffère de celle d'une plaine Int32: peut-être qu'elle n'autorise pas les nombres négatifs ^*ou n'autorise pas plus de sept chiffres. Vos utilisateurs internes peuvent prendre cela pour acquis, car ils regardent les numéros de série jour après jour, mais les utilisateurs externes peuvent être vraiment surpris de voir une exception à ce qui ressemble à un innocent passeur.

Vous avez absolument raison d'éviter de tels commentaires inutiles. Ils rendent la lecture du code plus difficile au lieu de le rendre plus facile et prennent trop de place.

Dans ma pratique, les gens qui écrivent des commentaires avec des getters / setters ont tendance à omettre les commentaires quand ils sont vraiment nécessaires (comme construire une requête sql de 20 lignes pour un composant sans documentation).

J'écris des commentaires lorsqu'il existe d'autres solutions évidentes _ J'indique pourquoi cette approche a été utilisée. Ou quand il est difficile de se faire une idée sans connaître tous les détails _ Je liste brièvement les détails nécessaires pour comprendre le code.

L'exemple que vous apportez est plus d'écrire des commentaires pour dire que l'on écrit des commentaires plutôt que de rendre la vie des autres (et la leur aussi) plus facile.

BTW vous pouvez améliorer votre capacité à écrire des commentaires en revenant à votre ancien code et en essayant de le comprendre (vous pourriez même ne pas reconnaître votre propre code en 2-3 mois - c'est absolument comme lire le code de quelqu'un d'autre). Si vous faites cela sans douleur, alors tout va bien.