J'étais un fan d'exiger des commentaires XML pour la documentation. J'ai depuis changé d'avis pour deux raisons principales:
- Comme un bon code, les méthodes doivent être explicites.
- 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; }
}
2
Je dirais que XML est un choix terrible à cet effet. C'est beaucoup trop verbeux et général pour l'utilisation à portée de main. Découvrez reStructuredText et sphinx pour un langage de balisage qui s'intègre dans les commentaires sans les rendre illisibles.
—
Latty
@Lattyware: VisualStudio prend en charge ce style par défaut, aucun plugin ou outil supplémentaire n'est nécessaire. Les commentaires générés de cette façon sont immédiatement visibles dans les info-bulles contextuelles.
—
FrustratedWithFormsDesigner
@FrustratedWithFormsDesigner Je dirais que l'obtention d'un plugin en vaut la peine pour rendre votre code beaucoup plus lisible. La prise en charge intégrée de reST avec des info-bulles comme celle-ci se trouve dans PyCharm, donc je suis sûr que des plugins existent pour d'autres langues dans d'autres IDE. Évidemment, si vous avez un projet où tout est documenté de cette façon, je ne vous suggère pas de commencer à diviser la façon dont il est fait, mais pour les nouveaux projets, je pense juste que c'est tellement horrible à lire et à maintenir.
—
Latty