Clean Code: Comments ที่ดีและไม่ดี

Clean Code: Comments ที่ดีและไม่ดี

ในบทความที่แล้ว เราได้พูดถึงหลักการเขียนฟังก์ชันที่ดีตามแนวคิด Clean Code ไม่ว่าจะเป็น Single Responsibility Principle (SRP), การทำให้ฟังก์ชันมีขนาดเล็ก และการหลีกเลี่ยง Side Effects ในบทความนี้ เราจะมาเจาะลึกเรื่องของ Comments และวิธีเขียน Comments ที่มีประโยชน์ รวมถึง Comments ที่ควรหลีกเลี่ยง เพื่อให้โค้ดของเราอ่านง่ายและเข้าใจได้ง่ายยิ่งขึ้น

Comments: ดาบสองคม

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

เป้าหมายหลักของการเขียนโค้ดที่ดีคือการทำให้โค้ดสามารถอธิบายตัวเองได้ (Self-Documenting Code) นั่นหมายความว่า โค้ดควรจะอ่านง่ายและเข้าใจได้โดยไม่ต้องพึ่งพา Comments มากนัก แต่ในบางสถานการณ์ Comments ก็ยังมีความจำเป็นอยู่

Comments ที่ดี: อธิบายเจตนา

Comments ที่ดีควรจะอธิบาย "เจตนา" (Intent) ของโค้ด ไม่ใช่แค่ "สิ่งที่" โค้ดทำ เพราะสิ่งที่โค้ดทำนั้น เราสามารถอ่านได้จากตัวโค้ดเองอยู่แล้ว

ตัวอย่างเช่น:

// คำอธิบายที่ไม่ดี: เพิ่มค่า 1 ให้กับตัวแปร counter
$counter++;

// คำอธิบายที่ดี: เพิ่มจำนวนผู้เข้าชมเว็บไซต์วันนี้
$counter++;

ในตัวอย่างแรก Comments บอกแค่ว่าเราเพิ่มค่า 1 ให้กับตัวแปร `counter` ซึ่งไม่จำเป็นต้องบอก เพราะโค้ดมันบอกอยู่แล้ว แต่ในตัวอย่างที่สอง Comments บอกว่าเรากำลังเพิ่มจำนวนผู้เข้าชมเว็บไซต์ ซึ่งช่วยให้เราเข้าใจบริบทและเจตนาของโค้ดได้ดีขึ้น

ตัวอย่างเพิ่มเติม:

// คำอธิบายที่ไม่ดี: วนลูปเพื่อประมวลผลข้อมูล
for ($i = 0; $i < count($data); $i++) {
  // ...
}

// คำอธิบายที่ดี: วนลูปเพื่อคำนวณยอดขายรวมของแต่ละสินค้า
for ($i = 0; $i < count($data); $i++) {
  // ...
}

อีกหนึ่งตัวอย่างที่แสดงให้เห็นว่าการอธิบายเจตนาสำคัญกว่าการอธิบายสิ่งที่โค้ดทำ

Comments ที่ดี: อธิบายเหตุผล

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

ตัวอย่างเช่น:

// เราต้องลบเครื่องหมายพิเศษออกจากชื่อไฟล์
// เพื่อให้สามารถใช้งานได้บนระบบปฏิบัติการ Windows
$filename = preg_replace('/[^a-zA-Z0-9\.]/', '', $filename);

ในตัวอย่างนี้ Comments อธิบายว่าทำไมเราถึงต้องใช้ `preg_replace` เพื่อลบเครื่องหมายพิเศษออกจากชื่อไฟล์ ซึ่งช่วยให้คนอื่นเข้าใจได้ว่าทำไมเราถึงเขียนโค้ดแบบนี้

Comments ที่ดี: แจ้งเตือนสิ่งที่ควรระวัง

Comments สามารถใช้เพื่อแจ้งเตือนเกี่ยวกับข้อจำกัดหรือสิ่งที่ควรระวังในการใช้งานโค้ดนั้นๆ ได้

ตัวอย่างเช่น:

// คำเตือน: ฟังก์ชันนี้ยังไม่รองรับการทำงานกับไฟล์ขนาดใหญ่
// อาจทำให้เกิด Memory Overflow ได้
function processFile($filename) {
  // ...
}

ในตัวอย่างนี้ Comments แจ้งเตือนว่าฟังก์ชัน `processFile` ยังไม่รองรับการทำงานกับไฟล์ขนาดใหญ่ และอาจทำให้เกิด Memory Overflow ได้ ซึ่งช่วยให้ผู้ใช้งานฟังก์ชันนี้ระมัดระวังในการใช้งาน

Comments ที่ไม่ดี: ซ้ำซ้อน

Comments ที่ซ้ำซ้อน คือ Comments ที่บอกสิ่งที่โค้ดบอกอยู่แล้ว Comments เหล่านี้ไม่มีประโยชน์ และทำให้โค้ดรก

ตัวอย่างเช่น:

// กำหนดค่า 0 ให้กับตัวแปร age
$age = 0;

// เพิ่มค่า 1 ให้กับตัวแปร count
$count++;

// ส่งคืนค่า true
return true;

Comments เหล่านี้ไม่มีประโยชน์ เพราะโค้ดมันบอกอยู่แล้วว่าเรากำลังทำอะไร

Comments ที่ไม่ดี: ข้อมูลที่ล้าสมัย

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

ดังนั้น หากเราแก้ไขโค้ด เราก็ควรตรวจสอบและอัปเดต Comments ที่เกี่ยวข้องด้วยเสมอ

Comments ที่ไม่ดี: มากเกินไป

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

หลักการทั่วไป: พยายามเขียนโค้ดที่สามารถอธิบายตัวเองได้ (Self-Documenting Code) มากที่สุดเท่าที่จะเป็นไปได้ ก่อนที่จะพึ่งพา Comments

ใช้ Comments เมื่อจำเป็น

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

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

ตัวอย่าง TODO:

// TODO: เพิ่มระบบการตรวจสอบความถูกต้องของข้อมูล
function saveData($data) {
  // ...
}

Comments ประเภท TODO ช่วยให้เราติดตามสิ่งที่ต้องทำในอนาคตได้ง่ายขึ้น

สรุป

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

ในบทความถัดไป เราจะมาพูดถึง CI/CD (Continuous Integration/Continuous Deployment) ซึ่งเป็นแนวคิดการทำ Automation สำหรับโปรเจกต์ PHP