คู่มือการเขียนคอมเมนต์โค้ดที่ดี

 (insight.infograb.net)
26 คะแนน โดย ironlung 2023-09-14 | 8 ความคิดเห็น | แชร์ทาง WhatsApp

  • บทบาทของคอมเมนต์โค้ด:

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

  • ความสำคัญของคอมเมนต์โค้ด:

    • คอมเมนต์แบบ inline ที่อยู่หน้าชุดโค้ดซับซ้อนช่วยประหยัดเวลาให้กับนักพัฒนาคนอื่นที่จะกลับมาดูโค้ดในภายหลัง
    • ยิ่งโปรเจกต์พัฒนาไปมากเท่าไร การทิ้งบริบทของการตัดสินใจในอดีตไว้ก็ยิ่งช่วยนักพัฒนาคนอื่นได้มากขึ้น
    • หากโค้ดมีความซับซ้อน ก็ควรมีอย่างน้อยคอมเมนต์แบบ inline สั้น ๆ นำหน้าไว้
    • การจะสื่อบริบทของการตัดสินใจและข้อมูลอีกหลายอย่างผ่านตัวโค้ดเพียงอย่างเดียวนั้นมีข้อจำกัด

  • วิธีเขียนคอมเมนต์โค้ดที่ดี:

    1. เขียนให้กระชับ
      • เขียนคอมเมนต์โดยใส่เฉพาะข้อมูลสำคัญเมื่อจำเป็นจริง ๆ
        • เมื่อโค้ดซับซ้อนจนหลีกเลี่ยงไม่ได้
        • เมื่อต้องเพิ่มรายละเอียดเพื่อให้มีความแม่นยำมากขึ้น
        • เมื่อขาดบริบท (เช่น ใช้โค้ดจากรีโพซิทอรีหรือแพ็กเกจอื่น)
      • ลดความสับสนและความกำกวมในคอมเมนต์ พร้อมให้บริบทและข้อมูลที่มีประโยชน์
    2. ใช้คอมเมนต์ TODOs/FIXMEs
      • คอมเมนต์ TODOs/FIXMEs เป็นวิธีแสดงว่า ‘งานในบางส่วนของโค้ดยังไม่เสร็จ หรือจำเป็นต้องแก้ไข’
      • เขียนในลักษณะเช่น “TODO: ต้องเพิ่มฟีเจอร์ XX” ไว้หน้าฟังก์ชัน
      • ระหว่างเขียนโค้ด หากคิดว่า 'ส่วนนี้ควรกลับมาดูอีกทีภายหลัง' หรือ 'ฟีเจอร์นี้ควรพัฒนาต่อในอนาคต' การใช้วิธีนี้จะช่วยบันทึกและติดตามประเด็นที่เกี่ยวข้องได้
      • Extension ที่น่าใช้: TODO Highlight
    3. อย่าใช้คอมเมนต์เพื่อแก้ตัวแทนโค้ด
      • แทนที่จะใส่คอมเมนต์เพื่อแก้ตัวให้โค้ดที่ผิดหรือไม่ชัดเจน ควรเขียนโค้ดใหม่
      • บางโค้ดจำเป็นต้องอธิบายด้วยคอมเมนต์ แต่บางโค้ดก็ควรสื่อความหมายได้ด้วย ‘ตัวโค้ดเอง’ โดยไม่ต้องพึ่งคอมเมนต์
    4. ใช้ AI ให้เป็นประโยชน์
      • หากใช้ตัวสร้างคอมเมนต์ด้วย AI ก็สามารถสร้างคอมเมนต์ในรูปแบบที่สม่ำเสมอตามมาตรฐานที่กำหนดได้
      • ช่วยรักษาความสอดคล้องของคอมเมนต์ทั้งโปรเจกต์ ทำให้อ่านโค้ดได้ง่ายขึ้น
      • เครื่องมือสร้างคอมเมนต์ด้วย AI ที่น่าใช้: Readable

บทความที่เกี่ยวข้อง

8 ความคิดเห็น

 
penza1 2023-09-19

ถ้ารู้สึกว่าโค้ดนี้ต้องมีคอมเมนต์
ก็ลองคิดดูก่อนไหมว่า หรือจริง ๆ แล้วโค้ดอาจจะเขียนผิดอยู่

คอมเมนต์ที่ไม่ได้มีชีวิตและทำงานไปพร้อมกับโค้ด
อาจสร้างความสับสนให้กับนักพัฒนาที่จะมาอ่านคอมเมนต์นั้นในอนาคต หรือแม้แต่ตัวเราเองก็ได้

แม้ว่าบริบทในอดีตจะไม่เกี่ยวข้องกับปัจจุบันแล้ว หรือเคยเป็นสาเหตุของข้อผิดพลาด
เราก็อาจลังเลที่จะปรับแก้สิ่งปัจจุบันเพราะข้อความที่อธิบายบริบทในอดีตนั้น หรืออ้อมไปแก้ด้วยโครงสร้างแบบอื่นแทน
และอาจยิ่งทำให้เกิดความผิดพลาดมากขึ้นด้วย..

จากประสบการณ์แล้ว คอมเมนต์ที่ช่วยให้รู้ว่าอะไรเคยถูกในตอนนั้น แต่ทำไมถึงผิดในตอนนี้ มีอยู่ไม่มากนัก....
 
ironlung 2023-09-19

ขอบคุณมากสำหรับการแบ่งปันความคิดเห็นอันมีค่า พอลองทบทวนความคิดเห็นที่คุณแบ่งปัน ก็รู้สึกว่าเพื่อพัฒนาโค้ดให้ดีขึ้น เราเองก็ควรพยายามตั้งคำถามอย่างรอบคอบถึงความจำเป็นของคอมเมนต์ด้วยเช่นกัน :)
 
aqqnucs 2023-09-18

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

พอดูอันนี้แล้ว ผมก็พยายามไม่เขียนคอมเมนต์มากเกินไปอีกเหมือนกัน
 
ironlung 2023-09-18

ขอบคุณที่แชร์วิดีโอดี ๆ นะครับ! :)
 
iamchanii 2023-09-15

ไม่ว่าถนนจะถูกปูไว้อย่างดีแค่ไหน ผมก็คิดว่าป้ายบอกทางยังคงจำเป็นเสมอ ดังนั้นช่วงนี้ผมเลยพยายามทำให้การเขียนคอมเมนต์เป็นนิสัยครับ
 
ironlung 2023-09-15

ขอบคุณที่ร่วมแบ่งปันมุมมองผ่านคอมเมนต์นะครับ พอได้คิดตามสิ่งที่คุณพูดมาก็ทำให้ย้อนกลับมาทบทวนว่า คอมเมนต์เองก็เป็น technical writing ที่สำคัญอย่างหนึ่ง จึงทำให้นึกกลับไปถึงหลักพื้นฐานของการเขียนอีกครั้งครับ :)
 
balak 2023-09-15

ผมคิดว่าสิ่งที่ดีที่สุดคือการเขียนโค้ดให้เข้าใจได้แม้ไม่มีคอมเมนต์
 
ironlung 2023-09-15

ครับ ผมก็คิดว่าการยึดพื้นฐานให้มั่นคงเป็นสิ่งสำคัญก่อน ขอบคุณสำหรับคอมเมนต์ครับ :)