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

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

1. TODO และ Fix it

ส่วนใหญ่เกิดมาจาก IDE ทำการสร้างให้อัตโนมัติ
และ developer เองก็ไม่ได้ลบออก

บางครั้ง developer เขียนไว้
เพื่อระบบจุดที่ต้องกลับมาแก้ไข และ ทำต่อ
แต่จนแล้วจนรอด ก็ไม่ได้กลับมาทำ

สุดท้ายมันจึงเป็น comment ที่ไร้ค่าอย่างมาก
ส่วน Fix it จะเขียนไว้ทำไมนะ น่าคิดนะ

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

เช่น

return true;  //return true

//private instance variable to keep age
public static int age;

แบบนี้ก็ไม่รู้จะเขียนไปทำแมวอะไร !!

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