Раніше я любив вимагати коментарів XML для документації. З тих пір я передумав з двох основних причин:
- Як і хороший код, методи повинні бути зрозумілими.
- На практиці більшість коментарів XML - це марний шум, який не надає додаткової цінності.
Багато разів ми просто використовуємо GhostDoc для генерування загальних коментарів, і саме це я маю на увазі під марним шумом:
/// <summary>
/// Gets or sets the unit of measure.
/// </summary>
/// <value>
/// The unit of measure.
/// </value>
public string UnitOfMeasure { get; set; }
Для мене це очевидно. Сказавши, що, якщо були спеціальні інструкції для включення, ми повинні абсолютно використовувати коментарі XML.
Мені подобається цей уривок із цієї статті :
Іноді вам потрібно буде написати коментарі. Але, це має бути винятком не з правила. Коментарі можна використовувати лише тоді, коли вони виражають щось, що неможливо виразити в коді. Якщо ви хочете написати елегантний код, прагніть усунути коментарі, а замість цього напишіть код самодокументування.
Я помиляюся, вважаючи, що ми повинні використовувати коментарі XML лише тоді, коли код недостатньо, щоб пояснити себе самостійно?
Я вважаю, що це хороший приклад, коли коментарі XML роблять гарний код некрасивим. Він займає такий клас, як цей ...
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; }
}
... І перетворює це на це:
/// <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
Я б стверджував, що XML - це страшний вибір для цієї мети. Це занадто багатослівний і загальний для використання. Ознайомтеся з реструктуризованим текстом та сфінксом щодо мови розмітки, яка вбудовується в коментарі, не роблячи їх нечитабельними.
—
Латті
@Lattyware: VisualStudio підтримує цей стиль за замовчуванням, додаткові плагіни та інструменти не потрібні. Коментарі, створені таким чином, відразу видно у спливаючих підказках.
—
FrustratedWithFormsDesigner
@FrustratedWithFormsDesigner Я б сказав, що отримання плагіна варто того, щоб зробити ваш код набагато читабельнішим. Вбудована підтримка reST з такими підказками, як у PyCharm, тому я впевнений, що плагіни існують для інших мов інших IDE. Очевидно, якщо у вас є проект, де все зафіксовано таким чином, я не пропоную почати ділити так, як це робиться, але для нових проектів я просто думаю, що це так жахливо читати та підтримувати.
—
Латті