“ รับหรือกำหนด .. ” จำเป็นในเอกสารประกอบ XML ของคุณสมบัติหรือไม่

ฉันกำลังมองหาคำแนะนำวิธีปฏิบัติที่ดีที่สุดสำหรับความคิดเห็น XML ใน C # เมื่อคุณสร้างคุณสมบัติดูเหมือนว่าเอกสาร XML ที่ต้องการมีรูปแบบดังต่อไปนี้:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

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

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft ใช้แบบฟอร์มแรกดังนั้นจึงดูเหมือนเป็นแบบแผนโดยนัย แต่ฉันคิดว่าอันที่สองดีกว่าด้วยเหตุผลที่ฉันพูด

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

ฉันจะซาบซึ้งความคิดหรือลิงก์ไปยังแนวทางปฏิบัติที่เป็นทางการที่แนะนำ

ลายเซ็นอาจบอกรหัสอื่น ๆ ว่ามีการทำงานอะไรบ้าง อย่างไรก็ตามมันไม่ได้แสดงให้เห็นอย่างชัดเจนต่อ coder เนื่องจากเขาหรือเธอกำลังทำงานอยู่และเอกสาร XML นั้นมีไว้สำหรับคนที่จะบริโภคและไม่ใช่คอมไพเลอร์

ยกตัวอย่างเช่น

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

เมื่อดึง Intellisense ขึ้นเพื่อเข้าถึงหนึ่งในคุณสมบัติเหล่านี้จะไม่มีข้อบ่งชี้ใดที่สามารถเขียน, อ่านจากหรือทั้งสองอย่าง:

เช่นเดียวกันเมื่อดูเอกสารเรายังไม่แน่ใจ:

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

StyleCop ใช้Gets or Sets ...สัญกรณ์ที่จะบังคับใช้กฎSA1623

หน้าเชื่อมโยงจะแสดงกรณีอื่นที่คุณไม่ได้ระบุไว้:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

ตัวเลือกอื่น ๆ ที่คุณจะเป็นรายการ

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

VS

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

ซึ่งจะไม่ให้ข้อมูลเกี่ยวกับคำใบ้ Intellisense ว่าทรัพย์สินที่ถูกอ่านเท่านั้นคุณสามารถเกิดขึ้นกับการประชุมสำหรับกรณีนี้เกินไป แต่Gets ..., Gets or Sets...ไม่ใช้งานแล้วอย่าง IMO

นอกจากนี้ยังมีความแตกต่างอื่น ๆ ที่ระบุไว้ในกฎ StyleCop ซึ่งมีความชัดเจนโดยใช้Gets or Sets...แต่อาจจะไม่มี

นอกจากนี้เมื่อสร้างเอกสารจากบางสิ่งเช่น Doxygen หรือ Sandcastle สัญลักษณ์แบบเต็มจะทำให้เอกสาร API (ตัวอย่าง) ดีขึ้น

ครั้งเดียวที่ฉันเพิ่มข้อมูลเกี่ยวกับการรับและการตั้งค่าคุณสมบัติในความคิดเห็น XML คือเมื่อไม่ทำงานตามที่คาดไว้ (รับและตั้งค่าสาธารณะโดยตรง)

หากเป็นส่วนตัวหรือถ้าพวกเขามีตรรกะเพิ่มเติมแล้วฉันพูดถึงพวกเขามิฉะนั้นฉันเพียงแค่เอกสารความตั้งใจของทรัพย์สิน

ฉันจะมีความสุขมากขึ้นกับรุ่น verbose เพิ่มเติม

อีกตัวอย่างหนึ่งคือมีความคิดเห็นของ "การเพิ่มจำนวนตัวนับ" หลังจากนั้นการเพิ่มตัวแปรตัวนับ

เห็นได้ชัดว่ามีการตั้งค่า หากคุณมี setter ส่วนตัวมันจะชัดเจนเพราะคุณจะมีคำหลักส่วนตัว

ความคิดเห็นควรเพิ่มมูลค่าไม่ใช่แค่ความคิดเห็นในรูปแบบของรหัสที่แท้จริง