ฉันควรรวมอะไรไว้ในความคิดเห็นเอกสาร XML

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

ในกรณีของตัวจัดการเหตุการณ์การตั้งชื่อและพารามิเตอร์เป็นมาตรฐานและชัดเจน:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

ฉันมักจะมีคุณสมบัติง่าย ๆ ที่มีชื่อ (IMO) อย่างชัดเจนเพื่อให้การสรุปซ้ำซ้อน:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

ฉันไม่รู้สึกว่าความคิดเห็นดังกล่าวไม่ได้เพิ่มข้อมูลใด ๆ ที่ประกาศเองยังไม่ได้นำเสนอ ภูมิปัญญาทั่วไปน่าจะเป็นที่ความคิดเห็นที่ทำซ้ำรหัสที่ดีที่สุดคือไม่ได้เขียนไว้

เห็นได้ชัดว่าเอกสาร XML เป็นมากกว่าความคิดเห็นแบบอินไลน์รหัสปกติและจะมีความครอบคลุม 100% อะไรควรฉันจะเขียนในกรณีดังกล่าว? หากตัวอย่างเหล่านี้ตกลงพวกเขาเสริมคุณค่าอะไรบ้างที่ฉันอาจไม่เห็นคุณค่าในตอนนี้

ความคิดเห็นเอกสาร XML มีไว้สำหรับสมาชิกสาธารณะ

คอมไพเลอร์เตือนอย่างชัดเจนนี้:

ไม่มีความคิดเห็น XML สำหรับประเภทที่เปิดเผยต่อสาธารณะหรือสมาชิก 'Type_or_Member'

คุณควรเพิ่มความคิดเห็น XML ให้กับสมาชิกส่วนตัวเท่านั้นหากสมาชิกเหล่านั้นยังไม่ชัดเจนจากชื่อของพวกเขา

ความคิดเห็นที่บริสุทธิ์ที่นี่ดังนั้นลองคิดในสิ่งที่คุ้มค่า

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

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

อย่าแม้แต่จะรับฉันเริ่มต้นกับการใช้งานที่ไม่จำเป็นของและthis.Me.

ในฐานะที่เป็นข้อความด้านข้างฉันชอบที่จะมีส่วนเสริมของ Visual Studio ที่ให้ฉันสลับการแสดงความคิดเห็นของ xml (คำใบ้คำใบ้)

ในเอกสาร XML สมาชิกสาธารณะควรมีความละเอียดและสมบูรณ์ตามที่ @SLaks ได้กล่าวถึง

อย่างไรก็ตามพวกเขาสามารถเป็นประโยชน์กับสมาชิกส่วนตัวที่ได้รับการปกป้องหรือภายในเช่นกันเพราะ Visual Studio จะเติมค่า Intellisense และช่วยแนะนำเคล็ดลับเครื่องมือด้วยความคิดเห็น XML doc

ซึ่งหมายความว่า:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

อาจเป็นเอกสารเพียงพออย่างสมบูรณ์แบบ แต่:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

จะเห็นได้ง่ายขึ้นจากที่อื่น ๆ ในรหัสของคุณ

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

คำอธิบายพารามิเตอร์การข้ามอาจเป็นความคิดที่ไม่ดีสำหรับอดีตและไม่เป็นผลดีสำหรับภายหลัง

ฉันจะเพิ่ม (ในเอกสาร API สาธารณะโดยเฉพาะ) รวมถึงคุณสมบัติgetหรือไม่set:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

ไม่ชัดเจนจาก Intellisense ของ C # ว่ามีgetหรือsetไม่มี แต่การใส่ไว้ในความคิดเห็น XML จะหมายความว่าคุณสามารถบอกได้ทันทีจากคำแนะนำเครื่องมือ