Ero un fan del richiedere commenti XML per la documentazione. Da allora ho cambiato idea per due motivi principali:
- Come il buon codice, i metodi dovrebbero essere autoesplicativi.
- In pratica, la maggior parte dei commenti XML sono rumori inutili che non forniscono alcun valore aggiuntivo.
Molte volte usiamo semplicemente GhostDoc per generare commenti generici, e questo è ciò che intendo per rumore inutile:
/// <summary>
/// Gets or sets the unit of measure.
/// </summary>
/// <value>
/// The unit of measure.
/// </value>
public string UnitOfMeasure { get; set; }
Per me è ovvio. Detto questo, se ci fossero istruzioni speciali da includere, dovremmo assolutamente usare i commenti XML.
Mi piace questo estratto di questo articolo :
A volte, dovrai scrivere commenti. Ma dovrebbe essere l'eccezione non la regola. I commenti devono essere usati solo quando esprimono qualcosa che non può essere espresso nel codice. Se vuoi scrivere un codice elegante, cerca di eliminare i commenti e scrivi invece un codice autocompattante.
Sbaglio pensando che dovremmo usare i commenti XML solo quando il codice non è abbastanza per spiegarsi da solo?
Credo che questo sia un buon esempio in cui i commenti XML rendono il codice piuttosto brutto. Ci vuole una classe come questa ...
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; }
}
... E lo trasforma in questo:
/// <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
Direi che XML è una scelta terribile per questo scopo. È troppo prolisso e generale per l'uso a portata di mano. Dai un'occhiata a reStructuredText e sfinge per un linguaggio di markup che si integra nei commenti senza renderli illeggibili.
—
Latty,
@Lattyware: VisualStudio supporta questo stile per impostazione predefinita, non sono necessari plug-in o strumenti aggiuntivi. I commenti generati in questo modo sono immediatamente visibili nelle descrizioni dei comandi a comparsa.
—
FrustratedWithFormsDesigner,
@FrustratedWithFormsDesigner Direi che vale la pena procurarsi un plugin per rendere il codice molto più leggibile. Supporto integrato per reST con tooltip come quello in PyCharm, quindi sono sicuro che esistono plugin per altre lingue in altri IDE. Ovviamente se hai un progetto in cui tutto è documentato in questo modo, non sto suggerendo di iniziare a dividere il modo in cui è stato fatto, ma per i nuovi progetti, penso solo che sia così orribile da leggere e mantenere.
—
Latty,