เมื่อไหร่ควรเขียน Comment อธิบาย Code ทิ้งไว้
มีคำถามว่า เวลาที่เราเขียน Code แล้ว เราจะรู้ได้ยังไงว่าเมื่อไหร่ควรจะ comment ว่า code อะไรไป
ว่ากันตามตรง เหตุผลนึงที่เราไม่อยาก comment code ที่เราเขียนคือเราไม่อยากที่จะดูโง่ว่า ที่รู้สึกว่า เราต้องเขียน Comment อธิบายโค้ดของเรา ที่เราควรจะเข้าใจมันที่สุด
หรือบางครั้งก็รู้สึกว่า Code ที่เขียนก็อธิบายในตัวเองได้ดีแล้ว
ดังนั้นวิธีการหนึ่งที่น่าลองเพื่อที่จะดูว่า เราควร comment code ไหม คือ การกลับไปดู Code ที่ตัวเองเขียนในภายหลัง ว่ายังอธิบายเข้าใจเหมือนเดิมหรือไม่ โดยแบ่งเป็นระยะสั้น กับ กลาง เช่น ระยะสั้น 2–3 วัน กับ ระยะกลางเช่น 10–15 วัน
เช่น
ถ้ากลับไปอ่านโค้ดหลังจากเขียน Code แล้ว 2–3 วัน แล้วไม่สามารถเข้าใจ Code ที่ตัวเองเขียนได้ในเวลา 5 นาที ใน block-code ชุดนั้น ส่วนตัวว่ามันเป็น Red Flag แล้ว ควรจะ Refactor หรือ comment อธิบายอะไรสักอย่าง อาจจะเป็นหลักการที่ต้องเขียนอธิบาย หรืออะไรก็ตาม แต่ต้องไม่ลืมว่า นี่คือ code ที่พึ่งเขียน ถ้ามัน recover อะไรไม่ได้เลย มันประหลาดมากแล้ว
แต่ถ้าสามารถระลึกได้ ในช่วง 1–5 นาที อาจจะเขียน comment เพิ่มเติมไปสักนิดนึงใน main idea ของ Code ชุดนั้น แต่ถ้ายาวนานมากๆ ก็คงต้องมีการอธิบายเพิ่ม หรือ Refactor ต่อไป
ถ้ากลับไปอ่านโค้ดหลังเขียน Code แล้วสัก 1 สัปดาห์ แล้วเรายังเข้าใจอยู่ภายใน 1 นาที ถือว่าดีงาน
แต่ถ้าเกิน 2–3 นาที อาจจะต้องมี comment เสริมเล็กน้อย
สาเหตุที่ใช้ระยะสั้นและระยะกลาง มาพิจารณา ส่วนหนึ่งเป็นเรื่องของการ Recall ความเข้าใจของเรากลับมา
ในระยะสั้นควรที่จะ recall รายละเอียดต่างๆ ได้เร็วพอสมควร แต่ถ้าไม่สามารถที่จะ recall ได้เร็ว ทั้งๆ ที่พึ่งได้ทำ จะมีความเป็นไปได้ว่า สิ่งที่ทำอยู่อาจจะมีรายละเอียดที่ซับซ้อน ซึ่งในอนาคต ถ้าเราไม่ทำอะไร มันจะต้องระลึกชาตินานกว่านี้อีก จึงควรจะมีข้อมูลช่วยอธิบายไว้บ้าง แต่ตรงนี้ถ้าเราซึ่งเป็นเจ้าของโค้ดยังลืม แล้วภาษาอะไรกับคนอื่นที่จะมาดู ดังนั้น ก็ควรจะเขียนมันไว้สักหน่อย
ขณะที่การ recall ในระยะกลาง จุดสำคัญคือเราจะเริ่มจำเป็นก้อนนัวๆ ดังนั้นเวลาที่ใช้ในการ recall จะได้รับผลมาจากโครงสร้างและคีย์เวิร์ดที่เขียน ซึ่งบางครั้งเราอาจจะลืมคำไป ดังนั้นการใส่ comment เป็นประโยคกระชับ และมี keyword ที่สำคัญ จะช่วยได้ครับ
แต่ถ้ามันลืมจริง ก็คงต้องเขียนอรรถาธิบายไปเหมือนเดิมครับ
สุดท้ายอันนี้บอกก่อนว่าเป็นความเห็นส่วนตัวทั้งสิ้น และไม่เกี่ยวกับ comment convention ในภาพใหญ่ ซึ่งควรจะทำอยู่แล้ว เช่นการเขียนบอกว่า function นี้มี parameter, return อะไร
สำหรับเรื่องของ Recall ถ้าสนใจลองดูจาก Learning How to Learn ที่เป็น Course อยู่ใน Coursera หรือไม่ก็จากหนังสือ The power of Output ได้ครับ