อ่านบทความเรื่อง Best practices for writing code comments จาก StackOverflow
ทำการสรุปและคำแนะนำเกี่ยวกับการเขียน comment ใน code ที่ดี
เพื่อช่วยให้คุณภาพของ code ดีขึ้น

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

แต่ในการทำงานนั้น จำเป็นต้องเขียน comment
เพื่อทำการอธิบาย codeว่าทำงานอย่างไร
ว่าใช้งานอ่างไรว่าแก้ไขหรือปรับปรุงอะไร
ในบทความจึงมีคำแนะนำต่าง ๆ ดังนี้

ข้อที่ 1 ไม่ต้องเขียน comment ซ้ำกับ code

ข้อที่ 2 comment ที่ดี ไม่ใช่การอธิบาย code ที่ไม่ดีหรืออธิบายตัวเองไม่ได้

ข้อที่ 3-5 ถ้าเขียน comment ไม่ชัดเจน คลุมเครือ นั่นหมายความว่า code ที่เขียนมักจะมีปัญหาเสมอ

comment ที่ดีต้องไม่ทำให้เกิดความสับสน

ข้อที่ 6 ถ้าทำการ copy code มาใช้งาน ควรมีที่มาเสมอ

ควรใส่ที่มาหรือ link ด้วยเสมอรวมทั้งข้อมูลอื่น ๆ เช่น

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

ข้อที่ 7 ต้องเขียน commnet เสมอเมื่อทำการแก้ไข bug ต่าง ๆ

ข้อที่ 8 เขียน comment เพื่อระบุหรือบอกว่า ส่วนไหนยังพัฒนาไม่เสร็จหรือสมบูรณ์

น่าจะมีประโยชน์นะครับ
ขอให้สนุกกับการ coding

Tags:,,,