ทำไมต้องมีคอมเมนต์แบบ "ทำไมไม่"

• ทำไมถึงไม่เขียนคอมเมนต์แบบ "ทำไมไม่"? ไม่ใช่ทำไม "ไม่เขียนคอมเมนต์"
  • “ทำไมถึงไม่ทิ้งคอมเมนต์เกี่ยวกับ ‘ทำไมมันถึงไม่เวิร์ก’ ไว้ล่ะ? ผมไม่ได้ถามว่า ‘ทำไมถึงไม่ใส่คอมเมนต์’ นะ”

ทำไมต้องมีคอมเมนต์แบบ "ทำไมไม่"

• โค้ดเขียนด้วยภาษาของเครื่องที่มีโครงสร้าง ส่วนคอมเมนต์เขียนด้วยภาษามนุษย์ที่สื่อความหมายได้หลากหลาย
• หมายถึงอย่าใส่คอมเมนต์ว่าโค้ดทำ "อะไร" แต่ให้พยายามใส่ข้อมูลลงใน identifier ให้มากที่สุดเท่าที่ทำได้
• ช่วงหลังยังมีความเห็นว่าแม้แต่ "ทำไม" ก็ไม่ควรอยู่ในคอมเมนต์ แต่ควรใส่ไว้ใน LongFunctionNames หรือชื่อ test case แทน
• โค้ดเบสแบบ "self-documenting" คือการเพิ่มเอกสารผ่าน identifier

ตัวอย่างล่าสุด

• ตัวอย่างจาก Logic for Programmers
• เกิดปัญหาที่การ build epub ไม่สามารถแปลงสัญลักษณ์คณิตศาสตร์(\forall)ให้เป็นเครื่องหมาย(∀)ได้
• จึงเขียนสคริปต์เพื่อแทนที่โทเคนของสตริงคณิตศาสตร์เป็นยูนิโค้ดด้วยมือ
• เขียนแบบแทนที่สัญลักษณ์คณิตศาสตร์ 16 ตัวทีละตัว แต่แนวทางนี้ไม่มีประสิทธิภาพ
• แก้ด้วยการใส่คอมเมนต์ง่าย ๆ
  • "ทำซ้ำ 16 รอบต่อหนึ่งสตริง แต่ตอนนี้ในหนังสือมีสตริงคณิตศาสตร์แค่ 25 รายการ และส่วนใหญ่ยาวไม่ถึง 5 ตัวอักษร ดังนั้นก็ยังเร็วพออยู่ดี"

ทำไมจึงควรใส่คอมเมนต์

• เหตุผลที่ควรใส่คอมเมนต์ แม้โค้ดที่ช้าจะยังไม่ก่อปัญหา
• ในอนาคตโค้ดอาจกลายเป็นปัญหาได้
• คอมเมนต์แสดงให้เห็นว่าเราตระหนักถึง trade-off นี้อยู่
• เมื่อต้องกลับมาดูโปรเจกต์อีกครั้งภายหลัง จะเข้าใจได้ว่าทำไมถึงเขียนโค้ดที่ช้าแบบนั้น

ทำไม self-documenting จึงเป็นไปไม่ได้

• ชื่อฟังก์ชันยาวอย่าง RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs ไม่ได้อธิบาย trade-off จริง ๆ
• identifier ของฟังก์ชันและตัวแปรบรรจุข้อมูลได้เพียงอย่างเดียว
• แทนที่คอมเมนต์ด้วยการทดสอบก็ทำไม่ได้เช่นกัน
• self-documenting อธิบายว่าโค้ดทำอะไร แต่ข้อมูลเชิงลบอธิบายว่าโค้ดไม่ได้ทำอะไร

ข้อคาดเดาท้ายจดหมายข่าว

• ผู้เขียนสงสัยว่าคอมเมนต์แบบ "ทำไมถึงใช้ไม่ได้" จะมองเป็นกรณีโต้แย้งสมมุติฐานได้หรือไม่
• การสื่อสารของมนุษย์ในระดับนามธรรมทำให้ self-documenting เป็นไปไม่ได้หรือไม่?
• อุปมา ความไม่แน่นอน ข้ออ้างเชิงจริยธรรม ฯลฯ จะทำให้เป็น self-documenting ได้หรือไม่?

---

สรุปโดย GN⁺

• บทความนี้พูดถึงความสำคัญของคอมเมนต์ในโค้ดและข้อจำกัดของมัน
• คอมเมนต์ช่วยให้ trade-off ในโค้ดชัดเจนขึ้น และทำให้การบำรุงรักษาในอนาคตง่ายขึ้น
• เน้นย้ำข้อจำกัดของ self-documenting และความจำเป็นของคอมเมนต์

[GN⁺]

ความเห็นจาก Hacker News

• เวลาเขียนคอมเมนต์ในโค้ด ควรอธิบายเป็นหลักว่า "ทำไม" และ "ทำไมถึงใช้ไม่ได้"; ถ้าเป็นโค้ดที่ซับซ้อน การอธิบายสั้นๆ ว่า "ทำอะไร" ก็มีประโยชน์เช่นกัน

  • คอมเมนต์แบบบังคับไม่มีประสิทธิภาพ และการใส่คอมเมนต์ให้ทุกฟังก์ชันเป็นการเสียเวลา
  • คอมเมนต์ที่เครื่องมือเพิ่มให้อัตโนมัติก็ไม่มีประสิทธิภาพเช่นกัน

• วิศวกรระดับจูเนียร์มักเขียนคอมเมนต์อธิบายว่าโค้ดทำอะไร, วิศวกรระดับกลางอธิบายว่าทำไมถึงเขียนแบบนั้น, และวิศวกรระดับซีเนียร์อธิบายว่าทำไมถึงไม่เขียนด้วยวิธีอื่น

• ใช้เทมเพลตคอมเมนต์สำหรับผู้ดูแลรักษา

  • "โค้ดนี้เขียนแบบนี้ด้วยเหตุผลว่า <เหตุผล> หากคุณพยายามแก้ไขแล้วพบว่าเป็นความผิดพลาดของตัวเอง โปรดเพิ่มตัวนับไว้ให้คนถัดไป: total_hours_wasted_here = n"

• การใส่คอมเมนต์ในส่วนที่ชวนให้แปลกใจของโค้ดเป็นเรื่องสำคัญ

  • เมื่อไม่มั่นใจว่าในอนาคตจะยังเข้าใจโค้ดนี้ได้หรือไม่ ก็ควรเขียนคอมเมนต์อธิบายว่า "ทำไมถึงใช้ไม่ได้"

• เน้นย้ำความสำคัญของคอมเมนต์ โดยเฉพาะเมื่อคุณต้องบำรุงรักษาโค้ดของตัวเองต่อไปอีก 5, 10 หรือ 15 ปี

  • การรักษาความสอดคล้องกับโค้ดเดิมเป็นสิ่งสำคัญ

• ควรใส่คอมเมนต์กับส่วนที่ "ไม่ใช่วิธีแก้แบบตรงไปตรงมา"

  • โค้ดที่ดูไม่มีประสิทธิภาพอาจก่อปัญหาได้เมื่อถูกแก้ไขในภายหลัง

• การใส่คอมเมนต์ไว้ในชื่อฟังก์ชันที่ยาวหรือชื่อเทสต์เคสก็เป็นแนวทางที่ดี

  • คอมเมนต์ช่วยได้เมื่อชื่อเมธอดไม่ชัดเจน
  • ถ้าคำอธิบายของเมธอดมีคำว่า "และ" อยู่ แสดงว่าเมธอดนั้นกำลังทำหลายอย่างเกินไป

• การเพิ่มคำเตือนผ่าน debug logging ก็มีประโยชน์ เมื่ออินพุตมีขนาดใหญ่เกินกว่าข้อจำกัดตามที่ออกแบบไว้เดิม

• ชอบใช้คอมเมนต์และ doc comment จำนวนมาก

  • เขียนคอมเมนต์แยกตามแต่ละขั้นของแอปพลิเคชัน และค่อยๆ แยกย่อยคอมเมนต์ไปพร้อมกับการเขียนโค้ด
  • ชอบใส่คอมเมนต์ให้ทุกฟังก์ชันและทุกตัวแปร

• ใน code review มักเขียนคอมเมนต์ว่า "เหตุผลที่ไม่ได้ทำ X คือ Y" เพื่อกันคำวิจารณ์ที่คาดว่าจะเจอล่วงหน้า