อ่านบทความเรื่อง Best practices for writing code comments จาก StackOverflow
ทำการสรุปและคำแนะนำเกี่ยวกับการเขียน comment ใน code ที่ดี
เพื่อช่วยให้คุณภาพของ code ดีขึ้น
มีประโยคที่น่าสนใจคือการเขียน comment ที่แย่ ๆ มันแย่กว่าการไม่เขียนอีกนะ
ดังนั้นเราไม่ควรเขียน comment ใช่หรือไม่ ?
เพราะว่า แม้จะเขียนไม่ดี compiler ก็ไม่ได้ตรวจสอบให้
ถ้า comment ไม่ตรงกับการทำงานจริง ก็ไม่มีอะไรเกิดขึ้น
ดังนั้นการเขียนมันใช้ทั้งเวลาและความพยายาม !!
แต่ในการทำงานนั้น จำเป็นต้องเขียน comment
เพื่อทำการอธิบาย codeว่าทำงานอย่างไร
ว่าใช้งานอ่างไรว่าแก้ไขหรือปรับปรุงอะไร
ในบทความจึงมีคำแนะนำต่าง ๆ ดังนี้
ข้อที่ 1 ไม่ต้องเขียน comment ซ้ำกับ code
[gist id="f236d5815683d63f9441e781fb695c16" file="1.java"]ข้อที่ 2 comment ที่ดี ไม่ใช่การอธิบาย code ที่ไม่ดีหรืออธิบายตัวเองไม่ได้
[gist id="f236d5815683d63f9441e781fb695c16" file="2.java"]ข้อที่ 3-5 ถ้าเขียน comment ไม่ชัดเจน คลุมเครือ นั่นหมายความว่า code ที่เขียนมักจะมีปัญหาเสมอ
comment ที่ดีต้องไม่ทำให้เกิดความสับสน
ข้อที่ 6 ถ้าทำการ copy code มาใช้งาน ควรมีที่มาเสมอ
ควรใส่ที่มาหรือ link ด้วยเสมอรวมทั้งข้อมูลอื่น ๆ เช่น
- ปัญหาที่แก้ไขคืออะไร
- code มาจากใคร
- ทำไมถึงเลือกใช้วิธีแก้ไขหรือ code ชุดนี้
- สามารถปรับปรุงได้อย่างไร
ข้อที่ 7 ต้องเขียน commnet เสมอเมื่อทำการแก้ไข bug ต่าง ๆ
[gist id="f236d5815683d63f9441e781fb695c16" file="7.java"]ข้อที่ 8 เขียน comment เพื่อระบุหรือบอกว่า ส่วนไหนยังพัฒนาไม่เสร็จหรือสมบูรณ์
[gist id="f236d5815683d63f9441e781fb695c16" file="8.java"]
น่าจะมีประโยชน์นะครับ
ขอให้สนุกกับการ coding