ความคิดเห็นของวิธีการควรมีทั้งบทสรุปและคำอธิบายการส่งคืนเมื่อพวกเขามักจะคล้ายกันมาก?

ฉันแสดงของรหัสเอกสารอย่างถูกต้องและผมตระหนักดีถึงข้อเสียเป็นไปได้ของมัน นั่นอยู่นอกขอบเขตของคำถามนี้

ฉันชอบที่จะปฏิบัติตามกฎของการเพิ่มความคิดเห็น XMLสำหรับสมาชิกสาธารณะทุกคนพิจารณาว่าฉันชอบ IntelliSense ใน Visual Studio มากแค่ไหน

มีรูปแบบหนึ่งของความซ้ำซ้อนซึ่งแม้กระทั่งผู้วิจารณ์ที่มากเกินไปอย่างฉันก็ใส่ใจด้วย ตัวอย่างเช่นใช้List.Exists ()

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryและreturnsโดยทั่วไปก็พูดในสิ่งเดียวกัน ฉันมักจะเขียนบทสรุปเพิ่มเติมจากreturnsมุมมองโดยวางreturnsเอกสารโดยรวม

ผลตอบแทนจริงเมื่อรายการมีองค์ประกอบที่ตรงกับเงื่อนไขที่กำหนดโดยเพรดิเคตที่ระบุเท็จอย่างอื่น

นอกจากนี้เอกสารผลตอบแทนที่ไม่ปรากฏขึ้นใน IntelliSense ดังนั้นผมค่อนข้างเขียนข้อมูลใด ๆ summaryที่เกี่ยวข้องทันที

1. ทำไมคุณจำเป็นต้องเอกสารreturnsแยกจากsummary?
2. ข้อมูลใด ๆ เกี่ยวกับสาเหตุที่ Microsoft รับรองมาตรฐานนี้

คุณสามารถอนุมานจากอีกหนึ่ง แต่ผู้ที่ยังคงอยู่สองส่วนแยกจากกันเพราะมันจะช่วยให้มุ่งเน้นไปที่หนึ่งซึ่งสนใจคนเมื่อตรวจสอบ / ใช้รหัส

ยกตัวอย่างของคุณฉันอยากจะเขียน:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

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

• ทีนี้ลองจินตนาการว่าฉันกำลังใช้วิธีการของคุณและค่าตอบแทนที่ฉันได้รับนั้นแปลกมาก ตอนนี้ฉันไม่ต้องการที่จะรู้ว่าวิธีการทำอะไร แต่ฉันต้องการที่จะรู้อะไรบางอย่างเกี่ยวกับค่าตอบแทน ที่นี่มี<returns/>ส่วนช่วยและฉันไม่จำเป็นต้องอ่านบทสรุป

ในตัวอย่างนี้อีกครั้งคุณสามารถอนุมานสรุปจาก<returns/>และสรุปค่าส่งคืนที่คาดหวังจากสรุป แต่เมื่อนำอาร์กิวเมนต์เดียวกันไปสู่จุดสูงสุดไม่จำเป็นต้องจัดทำเอกสารวิธีการของคุณเลยในกรณีนี้: ชื่อของวิธีการที่ใส่เข้าไปข้างในList<T>โดยPredicate<T> matchที่อาร์กิวเมนต์ตัวเดียวนั้นค่อนข้างชัดเจน

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

การใช้งานของฉัน:
<summary>อธิบายสิ่งที่วิธีการ (เพื่อรับ<returns>)
<returns>อธิบายถึงค่าตอบแทน

เชื่อมโยงไปยัง <summary>MSDN:<returns>

ทำไมคุณถึงต้องส่งคืนเอกสารแยกต่างหากจากการสรุป

ฉันคิดว่าถ้าส่วนสรุปยาวจริงๆและเป็นคำอธิบายอาจเป็นประโยชน์ที่จะมีส่วนแยกสั้น ๆ ส่งคืนส่วนท้าย

ฉันมักจะเขียนเพียง<summary>บางส่วนในรหัสของฉันเองตามที่คุณพูดว่า "คืน_ "

ฉันใส่ข้อสังเกตใด ๆ ที่ผู้โทรควรรู้ว่าไม่ชัดเจนจากชื่อเมธอดและพารามิเตอร์ (และชื่อ) หวังว่าชื่อวิธีการและพารามิเตอร์จะทำให้ชัดเจนพอที่ความคิดเห็นจะสั้นมาก

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

• เอกสารวิธีการอธิบายสิ่งที่ผู้โทรภายนอกจำเป็นต้องรู้เท่านั้น มันไม่ได้พูดเกี่ยวกับวิธีการทำงานภายใน แต่กล่าวถึงก) สาเหตุที่ผู้โทรต้องการเรียกวิธีการนี้ข) สิ่งที่จะเป็นผลที่คาดว่าจะได้จากวิธีการโทร หากมีความจำเป็นต้องจัดทำเอกสารวิธีการทำงานของระบบฉันใส่มันลงในส่วนของโค้ดเอง
• หากวิธีการมีความซับซ้อนเพียงพอกับมันแล้วคำอธิบายทั่วไปและส่วน [ส่งคืน] ดูเหมือนจะเป็นธรรม คุณไม่ต้องการให้ผู้อ่านอ่านคำอธิบายทั้งหมดและพยายามอนุมานวิธีตีความค่าตอบแทน
• หากวิธีการนั้นง่ายมากจนเป็นวิธีที่ดีที่สุดในการอธิบายสิ่งที่กล่าวคือ "วิธีนี้ส่งคืนที่อยู่ของบุคคล" ฉันก็ข้ามส่วน [ส่งคืน] เนื่องจากการเพิ่มดูเหมือนจะขัดกับหลักการของ DRY และฉัน ผู้สนับสนุนรายใหญ่ของเรื่องนี้ วิธีการเข้าถึงหนึ่งซับจำนวนมากดูเหมือนจะตกอยู่ในหมวดหมู่นี้

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

true ถ้ารายการมีหนึ่งองค์ประกอบขึ้นไปที่ตรงกับเงื่อนไขที่กำหนดโดยเพรดิเคตที่ระบุ มิฉะนั้นเป็นเท็จ

กลายเป็น

จริงถ้าองค์ประกอบของรายการใดตรงกับกริยา; เท็จอย่างอื่น