나는 문서에 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 및 스핑크스 를 확인하십시오 .
—
Latty
@Lattyware : VisualStudio는 기본적으로이 스타일을 지원하므로 추가 플러그인이나 도구가 필요하지 않습니다. 이 방법으로 생성 된 주석은 팝업 툴팁에 즉시 표시됩니다.
—
FrustratedWithFormsDesigner
@FrustratedWithFormsDesigner 플러그인을 얻는 것이 코드를 훨씬 더 읽기 쉽게 만들 가치가 있다고 말할 것입니다. PyCharm과 같은 툴팁으로 reST를 기본적으로 지원하므로 다른 IDE의 다른 언어에 대한 플러그인이 있다고 확신합니다. 모든 것이 이런 식으로 문서화되어있는 프로젝트가 있다면 분명히 그 방법을 나누기 시작하는 것이 아니라 새 프로젝트의 경우에는 읽고 유지하는 것이 끔찍하다고 생각합니다.
—
Latty