ความเห็น XML เป็นเอกสารที่จำเป็นหรือไม่

ฉันเคยเป็นแฟนที่ต้องการแสดงความคิดเห็น XML สำหรับเอกสาร ฉันเปลี่ยนใจเนื่องจากเหตุผลหลักสองข้อ:

1. เช่นเดียวกับรหัสที่ดีวิธีการควรอธิบายด้วยตนเอง
2. ในทางปฏิบัติความคิดเห็น 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; }
}

หากความคิดเห็นของคุณมีลักษณะเช่นนี้:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

ใช่แล้วพวกเขาไม่ได้มีประโยชน์ทั้งหมด หากพวกเขาอ่านสิ่งนี้:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

ถ้าอย่างนั้นฉันก็บอกว่าพวกเขามีค่า ดังนั้นเพื่อตอบคำถามของคุณ: ความคิดเห็นมีความจำเป็นเมื่อพวกเขาพูดบางอย่างที่รหัสไม่ได้พูด

ข้อยกเว้น: เป็นการดีที่จะมีความคิดเห็นเกี่ยวกับสิ่งใดก็ตามที่สาธารณชนสามารถเข้าถึงได้หากคุณเขียนไลบรารี่ / API ที่จะเผยแพร่สู่สาธารณะ ฉันเกลียดการใช้ห้องสมุดและเห็นฟังก์ชั่นชื่อที่getAPCDGFSocket()ไม่มีคำอธิบายว่า APCDGFSocket คืออะไร (ฉันมีความสุขกับบางสิ่งที่ง่ายเหมือนThis gets the Async Process Coordinator Data Generator File Socket) ดังนั้นในกรณีนี้ฉันจะใช้เครื่องมือบางอย่างในการสร้างความคิดเห็นทั้งหมดแล้วปรับแต่งความคิดเห็นที่ต้องการด้วยตนเอง

นอกจากนี้ getters / setters ยังเป็นตัวอย่างที่ไม่ดีสำหรับ "มีความคิดเห็นหรือไม่" เพราะพวกเขามักจะค่อนข้างชัดเจนและความคิดเห็นไม่จำเป็น ความคิดเห็นมีความสำคัญมากขึ้นกับฟังก์ชั่นที่ใช้อัลกอริทึมซึ่งคำอธิบายว่าทำไมสิ่งต่าง ๆ จึงถูกทำไปในทางที่พวกเขาสามารถทำให้โค้ดเข้าใจได้ง่ายขึ้นและทำให้โปรแกรมเมอร์ในอนาคตทำงานได้ง่ายขึ้น

... และสุดท้ายฉันค่อนข้างมั่นใจว่าคำถามนี้เกี่ยวข้องกับความคิดเห็นทุกรูปแบบไม่ใช่เฉพาะคำถามที่จัดรูปแบบโดยใช้ XML (ซึ่งคุณใช้เพราะคุณทำงานในสภาพแวดล้อม. NET)

ความคิดเห็นที่ดูไร้ประโยชน์ต่อผู้ใช้ที่สามารถอ่านรหัสได้จะค่อนข้างมีประโยชน์สำหรับผู้ใช้ที่ไม่สามารถเข้าถึงแหล่งข้อมูลได้ สิ่งนี้เกิดขึ้นเมื่อมีการใช้คลาสเป็น API ภายนอกโดยบุคคลภายนอกองค์กรของคุณ: HTML ที่สร้างจากเอกสาร XML ของคุณเป็นวิธีเดียวที่จะเรียนรู้เกี่ยวกับคลาสของคุณ

ที่กล่าวว่าความคิดเห็นที่ย้ำชื่อวิธีการที่มีช่องว่างเพิ่มระหว่างคำยังคงไร้ประโยชน์ หากคลาสของคุณจะถูกนำไปใช้นอกองค์กรของคุณคุณจะต้องจัดทำเอกสารเพื่อไม่ให้ช่วงที่ถูกต้องสำหรับค่าของคุณ ตัวอย่างเช่นคุณควรจะพูดว่าการตั้งค่าที่UnitOfMeasureจะnullเป็นสิ่งผิดกฎหมายว่าค่าที่จ่ายให้กับหมาไม่ต้องมีช่องว่างที่จุดเริ่มต้นหรือที่ส่วนท้ายของสตริงและอื่น ๆ คุณควรจัดทำเอกสารช่วงLabelSerialNumberถ้ามันแตกต่างจากของธรรมดาInt32: บางทีมันอาจไม่อนุญาตให้มีตัวเลขติดลบ^*หรือไม่อนุญาตให้มีมากกว่าเจ็ดหลัก ผู้ใช้ภายในของคุณอาจรับอนุญาตเนื่องจากพวกเขาดูหมายเลขประจำวันและออก แต่ผู้ใช้ภายนอกอาจแปลกใจจริง ๆ ที่เห็นข้อยกเว้นจากสิ่งที่ดูเหมือนเป็นตัวตั้งผู้บริสุทธิ์

คุณพูดถูกเกี่ยวกับการหลีกเลี่ยงความคิดเห็นที่ไร้ประโยชน์ พวกเขาทำให้การอ่านรหัสยากขึ้นแทนที่จะทำให้ง่ายขึ้นและใช้พื้นที่มากเกินไป

ในทางปฏิบัติของฉันคนที่เขียนความเห็นด้วย getters / setters มักจะละเว้นความคิดเห็นเมื่อมีความจำเป็นจริงๆ (เช่นการสร้างแบบสอบถาม SQL 20- บรรทัดสำหรับองค์ประกอบที่ไม่มีเอกสารประกอบ)

ฉันเขียนความคิดเห็นเมื่อมีวิธีแก้ปัญหาที่ชัดเจนอื่น ๆ _ ฉันระบุว่าทำไมวิธีนี้จึงถูกนำมาใช้อย่างแน่นอน หรือเมื่อมันยากที่จะเข้าใจความคิดโดยไม่ทราบรายละเอียดทั้งหมด _ ฉันจะเขียนรายละเอียดสั้น ๆ ที่จำเป็นต่อการเข้าใจรหัส

ตัวอย่างที่คุณนำมาเป็นมากกว่าการเขียนความคิดเห็นที่จะบอกว่าคนเขียนความคิดเห็นมากกว่าทำให้คนอื่น (และพวกเขา) ชีวิตง่ายขึ้น

BTW คุณสามารถปรับปรุงความสามารถในการเขียนความคิดเห็นโดยกลับไปที่รหัสเดิมของคุณและพยายามที่จะเข้าใจมัน (คุณอาจจำรหัสของตัวเองไม่ได้ใน 2-3 เดือน _ ซึ่งเหมือนกับการอ่านรหัสของคนอื่น) หากคุณทำสิ่งนี้อย่างเจ็บปวดกว่าทุกอย่างก็โอเค