การคอมเม้นแบบหลายบรรทัดใช้เครื่องหมายอะไร

การเขียนคำอธิบายโค้ดแบบหลายบรรทัดในภาษาซี: เคล็ดลับสู่โค้ดที่อ่านง่ายและบำรุงรักษาได้ง่าย

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

ในภาษาซี (C Programming Language) การเขียน comment เป็นเรื่องง่ายและยืดหยุ่น ซึ่งมีทั้งแบบบรรทัดเดียวและแบบหลายบรรทัด บทความนี้จะเน้นไปที่การเขียน comment แบบหลายบรรทัด และให้คำแนะนำเพิ่มเติมเพื่อให้การเขียน comment ของคุณมีประสิทธิภาพมากยิ่งขึ้น

ทำไมต้องใช้ Comment แบบหลายบรรทัด?

Comment แบบหลายบรรทัดมีความสำคัญอย่างยิ่งเมื่อคุณต้องการ:

• อธิบายส่วนของโค้ดที่ซับซ้อน: เมื่อเจอกับฟังก์ชันที่ซับซ้อน หรือชุดคำสั่งที่ทำงานร่วมกัน การใช้ comment แบบหลายบรรทัดช่วยให้คุณสามารถอธิบายขั้นตอนการทำงาน เหตุผล และข้อมูลอื่นๆ ที่เกี่ยวข้องได้อย่างละเอียด
• ใส่รายละเอียดเพิ่มเติม: คุณสามารถใช้ comment แบบหลายบรรทัดเพื่อเพิ่มข้อมูลเกี่ยวกับตัวแปร ฟังก์ชัน หรือโครงสร้างข้อมูลที่อาจไม่ชัดเจนจากชื่อ หรือการใช้งานเพียงอย่างเดียว
• สร้างเอกสารประกอบ (documentation): Comment สามารถใช้เป็นฐานข้อมูลสำหรับสร้างเอกสารประกอบโค้ด โดยเฉพาะอย่างยิ่งเมื่อใช้ร่วมกับเครื่องมือสร้างเอกสารอัตโนมัติ (เช่น Doxygen)

เครื่องหมายที่ใช้ในการเขียน Comment แบบหลายบรรทัด

ในภาษาซี เราใช้เครื่องหมาย /* เพื่อเริ่มต้น comment แบบหลายบรรทัด และ */ เพื่อสิ้นสุด comment นั้น:

/*
    นี่คือ comment แบบหลายบรรทัด
    ที่สามารถครอบคลุมหลายบรรทัดได้อย่างอิสระ
    เหมาะสำหรับอธิบายส่วนของโค้ดที่ซับซ้อน
*/

เคล็ดลับเพื่อการเขียน Comment ที่ดี

• ความชัดเจนและกระชับ: เขียน comment ให้เข้าใจง่ายและตรงประเด็น หลีกเลี่ยงการใช้ศัพท์เทคนิคที่ไม่จำเป็น และพยายามใช้ภาษาที่ชัดเจน
• อธิบาย “ทำไม” ไม่ใช่แค่ “อะไร”: เน้นการอธิบายเหตุผลที่อยู่เบื้องหลังโค้ดมากกว่าแค่การอธิบายว่าโค้ดทำอะไร ตัวอย่างเช่น แทนที่จะเขียนว่า x = x + 1; /* เพิ่มค่า x */ ให้เขียนว่า x = x + 1; /* เพิ่มค่า x เพื่อเลื่อนไปยังองค์ประกอบถัดไปใน array */
• อัปเดต Comment เมื่อโค้ดเปลี่ยนแปลง: สิ่งสำคัญคือต้องรักษา comment ให้สอดคล้องกับโค้ด หากคุณแก้ไขโค้ด อย่าลืมอัปเดต comment ที่เกี่ยวข้องด้วย
• หลีกเลี่ยงการ Comment ที่ชัดเจนอยู่แล้ว: อย่าเขียน comment ที่อธิบายสิ่งที่เห็นได้ชัดเจนจากโค้ดอยู่แล้ว เช่น int age; /* ประกาศตัวแปร age */
• ใช้ Comment เพื่อ Disable โค้ดชั่วคราว: คุณสามารถใช้ comment แบบหลายบรรทัดเพื่อ “comment out” หรือ disable โค้ดบางส่วนชั่วคราวเพื่อการทดสอบ หรือการ Debug ได้

ตัวอย่างการใช้งาน Comment แบบหลายบรรทัด

สมมติว่าเรามีฟังก์ชันที่คำนวณหาค่าเฉลี่ยของตัวเลขใน array:

float calculate_average(int arr[], int size) {
    /*
        คำนวณค่าเฉลี่ยของตัวเลขใน array ที่กำหนด

        Parameters:
            arr: array ของตัวเลข integer
            size: ขนาดของ array

        Returns:
            ค่าเฉลี่ยของตัวเลขใน array หรือ 0 หาก array ว่างเปล่า
    */

    if (size <= 0) {
        return 0; // ป้องกันการหารด้วยศูนย์
    }

    int sum = 0;
    for (int i = 0; i < size; i++) {
        sum += arr[i];
    }

    return (float)sum / size;
}

ในตัวอย่างนี้ Comment แบบหลายบรรทัดอธิบาย:

• วัตถุประสงค์ของฟังก์ชัน
• Parameters ที่ฟังก์ชันรับ
• ค่าที่ฟังก์ชันส่งคืน

การเขียน comment ที่ดีไม่ใช่เรื่องยาก แต่ต้องอาศัยความใส่ใจและวินัยในการเขียนโปรแกรม การใช้ comment แบบหลายบรรทัดอย่างมีประสิทธิภาพจะช่วยให้โค้ดของคุณอ่านง่าย เข้าใจง่าย และบำรุงรักษาได้ง่ายขึ้น ซึ่งเป็นสิ่งสำคัญสำหรับการทำงานร่วมกันในทีม และการพัฒนาซอฟต์แวร์ที่มีคุณภาพสูง