Kiedyś byłem fanem wymagania komentarzy XML do dokumentacji. Od tego czasu zmieniłem zdanie z dwóch głównych powodów:
- Podobnie jak dobry kod, metody powinny być zrozumiałe.
- W praktyce większość komentarzy XML to bezużyteczny szum, który nie zapewnia żadnej dodatkowej wartości.
Wiele razy po prostu używamy GhostDoc do generowania ogólnych komentarzy, a to rozumiem przez bezużyteczny hałas:
/// <summary>
/// Gets or sets the unit of measure.
/// </summary>
/// <value>
/// The unit of measure.
/// </value>
public string UnitOfMeasure { get; set; }
Dla mnie to oczywiste. Powiedziawszy to, jeśli byłyby specjalne instrukcje do włączenia, powinniśmy bezwzględnie używać komentarzy XML.
Podoba mi się ten fragment tego artykułu :
Czasami będziesz musiał pisać komentarze. Ale powinien to być wyjątek, a nie reguła. Komentarze powinny być używane tylko wtedy, gdy wyrażają coś, czego nie można wyrazić w kodzie. Jeśli chcesz napisać elegancki kod, postaraj się wyeliminować komentarze, a zamiast tego napisz kod samodokumentujący.
Czy mylę się, sądząc, że powinniśmy używać komentarzy XML tylko wtedy, gdy kod nie wystarcza do samodzielnego wyjaśnienia?
Uważam, że to dobry przykład, w którym komentarze XML sprawiają, że ładny kod wygląda brzydko. To wymaga takiej klasy ...
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; }
}
... I zamienia to w to:
/// <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
Twierdziłbym, że XML jest strasznym wyborem do tego celu. Jest to zbyt szczegółowe i ogólne, aby można było z niego skorzystać. Sprawdź reStructuredText i sphinx, aby znaleźć język znaczników, który osadza się w komentarzach, nie czyniąc ich nieczytelnymi.
—
Latty
@Lattyware: VisualStudio domyślnie obsługuje ten styl, nie są wymagane żadne dodatkowe wtyczki ani narzędzia. Komentarze wygenerowane w ten sposób są natychmiast widoczne w wyskakujących podpowiedziach.
—
FrustratedWithFormsDesigner
@FrustratedWithFormsDesigner Powiedziałbym, że warto pobrać wtyczkę, aby kod był znacznie bardziej czytelny. Wbudowana obsługa reST z takimi podpowiedziami jest w PyCharm, więc jestem pewien, że istnieją wtyczki dla innych języków w innych IDE. Oczywiście, jeśli masz projekt, w którym wszystko jest udokumentowane w ten sposób, nie sugeruję, abyś zaczął dzielić sposób, w jaki to się robi, ale w przypadku nowych projektów, po prostu uważam, że jest to okropne do przeczytania i utrzymania.
—
Latty