คอมเมนต์เป็นสิ่งที่โปรแกรมเมอร์ทุกคนต้องเคยผ่าน เพราะอำนวยความสะดวกให้การเขียนโปรแกรมมากมาย ไม่ว่าจะเป็นการคอมเมนต์โค้ดที่ยังไม่ใช้งานออกไปก่อนเพื่อที่จะ Debug โปรแกรมได้ง่ายขึ้น หรืออาจจะเป็นการคอมเมนต์เพื่อให้ผู้ที่ทำงานด้วยกันอ่านโค้ดแล้วเข้าใจได้ง่ายขึ้น รวมถึงเพื่อให้ตัวผู้เขียนเองที่ต้องการกลับมาแก้ไขโค้ดในส่วนของฟังก์ชันนั้น ๆ สามารถทำความเข้าใจโค้ดได้ง่ายขึ้นอีกด้วย
แต่ถึงกระนั้น ในการคอมเมนต์โค้ดเพื่อให้ผู้อ่านเข้าใจโค้ดได้ง่ายขึ้นนั้น บางครั้งก็ไม่ได้มีประสิทธิภาพมากนัก เนื่องจากในการเขียนโปรแกรมจริง ๆ บางครั้งเราอาจจะไม่สะดวกจะย้อนกลับมาดูว่าฟังก์ชันที่เคยเขียนมาแล้วและนำกลับมาใช้ใหม่นั้น ทำงานอย่างไร การคอมเมนต์ให้เป็น document จึงมาช่วยในส่วนนี้ได้อย่างมาก
สำหรับวิธีการเขียนคอมเมนต์แบบ document หรือที่มีชื่อว่า JSDoc นั้นเขียนไม่ยาก ก่อนอื่นเรามาทำความเข้าใจรูปแบบการเขียนของมันก่อน
เริ่มจากการคลุม document ที่จะไม่เหมือนกับการคอมเมนต์ทั่ว ๆ ไป JSDoc จำเป็นต้องใช้ /** */ ในการคลุมคอมเมนต์ ซึ่งสามารถเขียนหลายบรรทัดได้โดยการใช้ * ขึ้นต้นบรรทัดทุกบรรทัด และจำเป็นต้องใส่ JSDoc ไว้ด้านบนของฟังก์ชันที่ต้องการจะอธิบาย
อย่างในรูปตัวอย่างด้านบนนี้จะเห็นได้ว่ามีการใส่ tag (@function) เพื่อเป็นการประกาศว่าจะอธิบาย function นี้ จากนั้นจึงใส่ชื่อของฟังก์ชัน แล้วตามด้วยคำอธิบาย
อย่างในรูปตัวอย่างด้านบนนี้จะเห็นได้ว่ามีการใส่ tag (@function) เพื่อเป็นการประกาศว่าจะอธิบาย function นี้ จากนั้นจึงใส่ชื่อของฟังก์ชัน แล้วตามด้วยคำอธิบาย
จะเห็นได้ว่าหลังจากใส่คำอธิบายไปแล้ว หากเราใช้ VSCode เป็น Compiler แล้วนำเมาส์ไปจ่อบนตัวฟังก์ชันดังภาพ ตัว Compiler จะแสดงคอมเมนต์ที่เราเขียนไว้ออกมา แต่ในฟังก์ชันยังไม่มีการบอกประเภทตัวแปรที่ใช้เป็น parameters และ ประเภทของตัวแปรที่ return ออกมา เราจึงควรอธิบายด้วย tag @param และ @return เพิ่มเติมด้วย
ในส่วนของ @param นั้นมีสิ่งที่เราจำเป็นต้องประกาศเพิ่มขึ้นมาคือชนิดของตัวแปร ซึ่งจำเป็นต้องมี {} คลุม และจากนั้นก็ใส่ชื่อของตัวแปร และคำอธิบายตามปกติ
ส่วนของ @return จำเป็นต้องประกาศในส่วนของชนิดตัวแปรเช่นเดียวกันแต่ไม่จำเป็นต้องมีชื่อของตัวแปร
และเมื่อเรานำเมาส์ไปจ่อที่ชื่อฟังก์ชัน จะได้ผลออกมาดังนี้
จะเห็นได้ว่าประเภทของตัวแปรได้ถูกเพิ่มข้ามายังคำอธิบายของฟังก์ชันแล้ว
นอกจากนี้ ในส่วน syntax ของ tag อื่น ๆ ใน JSDoc สามารถศึกษาเพิ่มเติมได้ที่ https://jsdoc.app/
และผมหวังเป็นอย่างยิ่งว่า ผู้อ่านทุกท่านจะได้รับประโยชน์จากการนำความรู้ในบทความนี้ไปประยุกต์ใช้ในการเขียนโปรแกรมไม่มากก็น้อย
เขียนโดย เธียรวิชญ์ สิริสาครสกุล
วันที่ 17 กันยายน 2564