เหตุใด /// บล็อกความคิดเห็นจึงมีความสำคัญ

มีคนเคยกล่าวว่าเราควรนำหน้าวิธีการทั้งหมดของเราด้วย /// <summary>บล็อกความคิดเห็น (C #) แต่ไม่ได้อธิบายว่าทำไม

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

มีเหตุผลที่ดีที่ใช้/// <summary>บล็อคความคิดเห็นในรหัสของคุณหรือไม่

ปกติฉันจะใช้//ความคิดเห็นตลอดเวลามันเป็นเพียง/// <summary>ช่วงเวลาที่ฉันสงสัย

ใช้พวกเขาให้มากที่สุด

ใช่เหล่านี้เป็นความคิดเห็นพิเศษที่เป็นเอกสารสำหรับวิธีการ เนื้อหาของ<summary>, แท็กพารามิเตอร์, ฯลฯ ที่สร้างขึ้นจะแสดงใน Intellisense เมื่อคุณหรือคนอื่นพร้อมที่จะเรียกวิธีการของคุณ พวกเขาสามารถดูเอกสารทั้งหมดสำหรับวิธีการหรือคลาสของคุณโดยไม่ต้องไปที่ไฟล์นั้นเพื่อหาว่ามันทำอะไร (หรือลองอ่านลายเซ็นวิธีและหวังว่าจะดีที่สุด)

ใช่ใช้สิ่งเหล่านี้กับทุกสิ่งที่คุณต้องการเก็บไว้หรืออาจถูกแชร์

นอกจากนี้ให้ใช้ร่วมกับSandcastleและตัวสร้างไฟล์ช่วยเหลือ Sandcastleซึ่งใช้เอาต์พุต XML และแปลงเป็นเอกสาร MSDN สไตล์ที่สวยงาม

สถานที่สุดท้ายที่ฉันทำงานเราสร้างเอกสารขึ้นใหม่ทุกคืนและโฮสต์เป็นหน้าแรกภายใน ชื่อย่อของ บริษัท คือ MF ดังนั้นจึงเป็น MFDN;)

โดยปกติแล้วฉันจะสร้างไฟล์. chm ซึ่งแบ่งปันได้อย่างง่ายดาย

คุณจะประหลาดใจที่คุณติดการบันทึกทุกอย่างเมื่อคุณเริ่มเห็นมันในรูปแบบ MSDN!

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

มิฉะนั้นให้พิจารณาอย่างจริงจังโดยไม่ใช้ความคิดเห็นดังกล่าว คุณสามารถหลีกเลี่ยงได้ในกรณีส่วนใหญ่โดยการเปลี่ยนรหัสของคุณเช่นนี้:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

ไปยัง

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

ไปยัง

    public bool IsAuthorizedToAccessResource( User user ) {

    }

คลาสวิธีการและการตั้งชื่อทรัพย์สินของคุณควรปรากฏชัดในตัวเองดังนั้นหากคุณต้องการสิ่งเหล่านี้อาจเป็นกลิ่น

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

แต่อย่างไรก็ตามคุณฝานมันรักษาหรือลบออก

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

อธิบายว่าการทำงานในความคิดเห็นละเมิด DRY อย่างไร หากรหัสของคุณไม่สามารถอธิบายตัวเองได้พอสมควรคุณควรกลับไปทำซ้ำอีกครั้ง

ใช่ฉันได้สร้างพวกเขา [เมื่อสร้างระบบใหม่ตั้งแต่เริ่มต้น]

ไม่ฉันไม่เคยได้รับประโยชน์จากพวกเขา [เมื่อทำงานกับระบบที่มีอยู่ซึ่งต้องการการบำรุงรักษา]

ฉันพบว่าความคิดเห็น "สรุป" ในที่สุดมีแนวโน้มที่จะไม่ตรงกับรหัส และเมื่อฉันสังเกตเห็นความคิดเห็นที่ประพฤติตัวไม่ดีฉันมักจะสูญเสียศรัทธาในความคิดเห็นทั้งหมดในโครงการนั้น - คุณไม่แน่ใจว่าจะเชื่อใจคนใด

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

มันเป็นหนึ่งในวิธีที่ชัดเจนที่สุดในการจัดทำรหัสของคุณ

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

" จะต้องมีการใช้งานเป็นอย่างมากเช่นฉัน;) "

ฉันเคยเล่นกับความคิดเห็น (///) สำหรับชั้นเรียนคุณสามารถแสดงความคิดเห็นแบบนี้ได้

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

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

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

คุณสามารถใช้ทางลัดในการสร้างความคิดเห็น(///+Tab)นี้

ใช้พวกเขายกเว้นสำหรับห้องสมุด

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

แต่สำหรับ internals ของโครงการปัจจุบันพวกเขาเพิ่งเข้ามา

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

ฉันใช้เทียบเท่าใน VB (เนื่องจากพวกเขาจะไม่ให้ฉันใช้ C # - เห็นได้ชัดว่ามันยากเกินไป ... ไม่มีความคิดเห็น) ฉันพบว่าพวกเขาสะดวกมาก เวลาส่วนใหญ่ที่ฉันรอจนกว่าขั้นตอนหรือฟังก์ชั่นจะเสร็จสมบูรณ์ค่อนข้างมากก่อนที่จะใส่พวกเขาหากเพียงเพื่อหลีกเลี่ยงการเปลี่ยนความคิดเห็น - หรือให้พวกเขา "ซิงค์"

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

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