ขั้นตอนการเขียนอธิบายคําสั่ง (Comment) ทั้ง 2 รูปแบบ มีขั้นตอนอย่างไร

การเขียน Comment ในภาษา C/C++: คู่มือฉบับละเอียด

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

1. Comment บรรทัดเดียว (Single-line Comment):

Comment แบบนี้ใช้สำหรับอธิบายโค้ดเพียงแค่บรรทัดเดียว เหมาะสำหรับการอธิบายฟังก์ชันสั้นๆ หรือคำอธิบายสั้นๆ เกี่ยวกับส่วนใดส่วนหนึ่งของโค้ด สัญลักษณ์ที่ใช้คือ // (สองเครื่องหมายทับ) ซึ่งจะทำให้คอมไพเลอร์ไม่นำข้อความหลังเครื่องหมาย // ไปประมวลผล

ขั้นตอนการเขียน:

1. วางเครื่องหมาย // ไว้ข้างหน้าข้อความที่ต้องการอธิบาย: ข้อความหลังเครื่องหมาย // จะเป็น Comment และจะไม่ถูกนำไปรัน
2. เขียนคำอธิบายที่ชัดเจนและสั้นกระชับ: พยายามใช้ภาษาที่เข้าใจง่าย ตรงประเด็น และเกี่ยวข้องกับโค้ดที่กำลังอธิบาย
3. เว้นวรรคอย่างเหมาะสม: การเว้นวรรคจะช่วยให้ Comment อ่านง่ายขึ้น

ตัวอย่าง:

int age = 30; // ตัวแปร age เก็บค่าอายุ
double salary = 50000.0; // ตัวแปร salary เก็บค่าเงินเดือน

ในตัวอย่างข้างต้น ข้อความหลังเครื่องหมาย // คือ Comment อธิบายว่าตัวแปร age และ salary เก็บค่าอะไร

2. Comment หลายบรรทัด (Multi-line Comment):

Comment แบบนี้ใช้สำหรับอธิบายโค้ดหลายบรรทัด เหมาะสำหรับการอธิบายฟังก์ชันที่ซับซ้อน หรืออธิบายส่วนโค้ดที่มีความยาว สัญลักษณ์ที่ใช้คือ /* (เครื่องหมายทับและเครื่องหมายดอกจัน) สำหรับเริ่มต้น Comment และ */ (เครื่องหมายดอกจันและเครื่องหมายทับ) สำหรับปิด Comment ข้อความที่อยู่ระหว่าง /* และ */ จะไม่ถูกนำไปประมวลผล

ขั้นตอนการเขียน:

1. *เริ่มต้น Comment ด้วย `/`:** นี่คือจุดเริ่มต้นของ Comment หลายบรรทัด
2. เขียนคำอธิบายที่ชัดเจน ครอบคลุม และเป็นระบบ: สามารถแบ่งย่อหน้า ใช้ bullet point หรือตัวหนาเพื่อเน้นจุดสำคัญ เพื่อให้ Comment อ่านง่าย และเข้าใจได้ง่ายขึ้น
3. *ปิด Comment ด้วย `/`:** นี่คือจุดสิ้นสุดของ Comment หลายบรรทัด

ตัวอย่าง:

/*
ฟังก์ชันนี้ใช้สำหรับคำนวณค่าเฉลี่ยของเลขจำนวนเต็ม n ตัว
พารามิเตอร์:
  - arr:  อาเรย์ของเลขจำนวนเต็ม
  - n:  จำนวนของเลขจำนวนเต็มในอาเรย์
ค่าส่งกลับ: ค่าเฉลี่ยของเลขจำนวนเต็มทั้งหมด
*/
double calculateAverage(int arr[], int n) {
  // ...โค้ดคำนวณค่าเฉลี่ย...
}

ในตัวอย่างนี้ Comment อธิบายอย่างละเอียดถึงฟังก์ชัน calculateAverage รวมถึงพารามิเตอร์และค่าที่ส่งกลับ

สรุป:

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