Tôi đã từng là một người hâm mộ yêu cầu các bình luận XML cho tài liệu. Tôi đã thay đổi suy nghĩ vì hai lý do chính:
- Giống như mã tốt, phương pháp nên tự giải thích.
- Trong thực tế, hầu hết các bình luận XML là tiếng ồn vô dụng không cung cấp thêm giá trị.
Nhiều lần chúng tôi chỉ đơn giản sử dụng GhostDoc để tạo bình luận chung chung, và đây là điều tôi muốn nói bởi tiếng ồn vô dụng:
/// <summary>
/// Gets or sets the unit of measure.
/// </summary>
/// <value>
/// The unit of measure.
/// </value>
public string UnitOfMeasure { get; set; }
Đối với tôi, đó là điều hiển nhiên. Phải nói rằng, nếu có các hướng dẫn đặc biệt để đưa vào, thì chúng ta hoàn toàn nên sử dụng các nhận xét XML.
Tôi thích đoạn trích từ bài viết này :
Đôi khi, bạn sẽ cần phải viết bình luận. Nhưng, nó phải là ngoại lệ không phải là quy tắc. Nhận xét chỉ nên được sử dụng khi chúng đang diễn đạt một cái gì đó không thể được thể hiện bằng mã. Nếu bạn muốn viết mã thanh lịch, hãy cố gắng loại bỏ các bình luận và thay vào đó hãy viết mã tự ghi.
Tôi có sai không khi nghĩ rằng chúng ta chỉ nên sử dụng các nhận xét XML khi mã không đủ để tự giải thích?
Tôi tin rằng đây là một ví dụ tốt trong đó các nhận xét XML làm cho mã đẹp trông xấu xí. Phải có một lớp học như thế này ...
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; }
}
... Và biến nó thành thế này:
/// <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
Tôi cho rằng XML là một lựa chọn tồi tệ cho mục đích này. Đó là cách quá dài dòng và chung chung cho việc sử dụng trong tầm tay. Kiểm tra reSturationuredText và sphinx để biết ngôn ngữ đánh dấu được nhúng vào các nhận xét mà không làm cho chúng không thể đọc được.
—
Latty
@Lattyware: VisualStudio hỗ trợ kiểu này theo mặc định, không cần thêm plugin hay công cụ nào. Nhận xét được tạo theo cách này có thể nhìn thấy ngay lập tức trong các chú giải công cụ bật lên.
—
Thất vọngWithFormsDesigner
@FrustratedWithFormsDesigner Tôi sẽ nói rằng việc có một plugin là xứng đáng để làm cho mã của bạn dễ đọc hơn nhiều. Hỗ trợ tích hợp cho reST với các chú giải công cụ như trong PyCharm, vì vậy tôi chắc chắn các plugin tồn tại cho các ngôn ngữ khác trong các IDE khác. Rõ ràng nếu bạn có một dự án mà mọi thứ đều được ghi lại theo cách này, tôi không khuyên bạn nên bắt đầu chia nhỏ cách thực hiện, nhưng đối với các dự án mới, tôi chỉ nghĩ rằng thật kinh khủng khi đọc và duy trì.
—
Latty