Раньше я был поклонником требования 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 - ужасный выбор для этой цели. Это слишком многословный и общий для использования под рукой. Проверьте reStructuredText и sphinx для языка разметки, который встраивается в комментарии, не делая их нечитаемыми.
—
Latty
@Lattyware: VisualStudio поддерживает этот стиль по умолчанию, дополнительные плагины или инструменты не требуются. Сгенерированные таким образом комментарии сразу видны во всплывающих подсказках.
—
FrustratedWithFormsDesigner
@FrustratedWithFormsDesigner Я бы сказал, что приобретение плагина стоит того, чтобы сделать ваш код более читабельным. Встроенная поддержка reST с всплывающими подсказками в PyCharm, так что я уверен, что плагины существуют для других языков в других IDE. Очевидно, что если у вас есть проект, где все задокументировано таким образом, я не предлагаю вам начинать разделять способ, которым это делается, но для новых проектов я просто думаю, что это так ужасно читать и поддерживать.
—
Латти