รูปแบบของ comment ใน code ที่เจอประจำ

จากการ review code จำนวนหนึ่ง จากการแก้ไขและปรับปรุง code จำนวนหนึ่ง พบว่าการเพิ่ม comment ใน code มันเป็นสาเหตุหนึ่งที่ส่งผลให้คุณภาพของ code แย่ลง ซึ่งมักจะมีรูปแบบดังนี้

1. TODO และ Fix it

ส่วนใหญ่เกิดมาจาก IDE ทำการสร้างให้อัตโนมัติ และ developer เองก็ไม่ได้ลบออก บางครั้ง developer เขียนไว้ เพื่อระบบจุดที่ต้องกลับมาแก้ไข และ ทำต่อ แต่จนแล้วจนรอด ก็ไม่ได้กลับมาทำ สุดท้ายมันจึงเป็น comment ที่ไร้ค่าอย่างมาก ส่วน Fix it จะเขียนไว้ทำไมนะ น่าคิดนะ

2. Comment ในสิ่งที่ code ทำอยู่แล้ว

เช่น [code] return true; //return true //private instance variable to keep age public static int age; [/code] แบบนี้ก็ไม่รู้จะเขียนไปทำแมวอะไร !!

3. เขียนคำเตือนไว้ใน code

ตัวอย่างเช่น อย่ามายุ่งกับ code ส่วนนี้ ถ้าไม่ได้รับอนุญาต พร้อมระบุชื่อ email และ เบอร์ติดต่อ บางครั้งก็เขียนขอโทษกับสิ่งที่ทำลงไป !!

4. เจอการ comment code จำนวนมาก

ถ้าไปถามคนที่ดูแล ว่า ทำไมไม่ลบ code ชุดนี้ไปล่ะ ? ทั้ง ๆ ที่ code ชุดนี้ถูก comment ไว้ ทั้ง ๆ ที่ code ถูกจัดเก็บไว้ใน version control ทั้ง ๆ ที่ ... แต่คำตอบที่ได้คือ อย่าไปลบมันเลย กลัวกระทบ เดี๋ยว code ชุดนี้อาจจะถูกนำกลับมาใช้อีก !! ดังนั้น ปล่อยไว้อย่างนั้นแหละนะ !!

5. อธิบายว่า เขียน code แบบนี้เนื่องมากจากใคร ?

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

สุดท้าย คือ Comment ที่ไม่ถูกต้อง ตามการทำงานจริงของ code !!

เป็นสิ่งที่น่ากลัวอย่างมาก สำหรับ developer ที่ต้องเข้ามาดูแล code ชุดนี้ สามารถพูดได้เลยว่า ไม่มี comment ยังดีกว่านะ !! ปล. ผมไม่ได้บอกว่า การเขียน comment ใน code เป็นสิ่งที่ไม่ดีนะ แต่ก่อนจะเขียนควรคิดก่อนว่า code ที่เขียนมันอธิบายตัวมันเองได้ไหม ? ถ้าไม่ได้ ให้ปรับปรุง code ก่อนดีไหม ? ถ้าต้องเขียนจริง ๆ ก็ต้องทำให้มันดี และ update อยู่อย่างเสมอ ตาม code ที่เปลี่ยนแปลง

แล้วคุณล่ะ เจอ comment ใน code แบบไหนกันบ้าง ?

Reference Websites http://www.hongkiat.com/blog/source-code-comment-styling-tips/ http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered https://dzone.com/articles/my-commentary-on-code-comments http://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code--net-8118