เขียน Code document ด้วย JSDoc
การเขียนโค้ดเนี้ย ถ้าเราเขียนแค่คนเดียวมันก็คงไม่มีปัญหาอะไรกับการนำโค้ดกลับมาอ่าน(มั่ง !?) แต่เมื่อไหร่ที่การเขียนโค้ดนั้นมีมากกว่า 1 คนขึ้นไปหรือเขียนกันเป็นทีม สิ่งที่จะต้องเกิดขึ้นเลยก็คือการอ่านโค้ดหรือเรียกใช้คำสั่งที่เราไม่ได้เป็นคนเขียนมันขึ้นมา แล้วต้องประสบพบเจอกับสิ่งที่ไม่คาดฝันเหล่านี้
ถ้าอ่านแค่ชื่อ function ก็พอจะเดาได้ว่า เจ้าฟังก์ชันนี่มันน่าจะทำการเช็คอะไรบางอย่างว่าเป็น Programmer หรือไม่ แล้ว return ค่าที่เป็น boolean ออกมาให้เรา(เดาจากชื่อ function) แต่ประเด็นก็คือ “แล้วฉันจะต้องส่งอะไรเข้าไปให้แกมั่งละเนี้ย” ทีนี้แหละคุณผู้ชมไล่อ่านโค้ดกันตราบนานเท่านาน เสียเวลากันเป็นชั่วโมงหรืออาจจะเป็นวัน
จะดีกว่าไหมถ้าเราสามารถเขียนคำอธิบายโค้ดของเราไว้ได้ จะได้ไม่ต้อง งง กันอีกต่อไป !?
JSDoc จะมาช่วยเราในเรื่องนี้ ไม่ต้องเขียนลงกระดาษให้เมื่อยมือ เขียนมันลงไปในโค้ดเรานี่แหละ โดย JSDoc จะเขียนอยู่ในรูปแบบของ comment ภายใน /** */
ถ้าคุณเป็นหนึ่งคนที่ใช้ vscode ในการเขียนโค้ดแล้วล่ะก็มันชั่งง่ายดายเหมือน Thanos ดีดนิ้ว เพียงแค่คุณพิมพ์ /** ไว้บน function หรือตัวแปรที่ต้องการ หลังจากนั้น vscode จะขึ้น snippet มาให้ เพียงแค่จิ้มปุ่ม enter เบาๆ เจ้า vscode ก็จะทำการสร้างโครงในการเขียน JSDoc มาให้ทันที
มาลองเขียนกัน
กลับมาที่ function เจ้าปัญหากัน ทำการพิมพ์ /** ไว้บน function หลังจากนั้นตัว vscode จะขึ้น snippet มาให้ดังนี้
จากนั้นกด enter
ผ่ามมม !!! ตัว vscode จะทำการสร้างโครงสำหรับการเขียน JSDoc มาให้ หลังจากนั้นเราก็แค่พิมพ์รายละเอียดที่เราต้องการจะอธิบายเกี่ยวกับฟังก์ชั่นนี้ลงไป
สังเกตว่าในบรรทัดที่ 2 คือการอธิบายตัวฟังก์ชันอย่างคร่าวๆ และในบรรทัดต่อไปจะเป็นการอธิบายว่า parameter ที่รับเข้ามานั้นมีอะไรบ้าง โดยรูปแบบการเขียนนั้นจะประกอบไปด้วย Type, ชื่อ parameter และคำอธิบาย parameter ตัวนั้นๆ ตามลำดับ
แล้วมันมีประโยชน์ตรงไหนกัน !?
เราลองเอาเมาส์ไปชี้ที่ฟังก์ชัน ผลลัพที่ได้คือ
ตัว vscode จะแสดง popup document ที่เราได้เขียนไว้ก่อนหน้านี้ เพื่ออธิบายให้ผู้ที่ต้องการเรียกใช้ได้เข้าใจว่าตัวฟังก์ชันนี้มีหน้าที่อะไร มีการรับ parameter อะไรบ้างและ return ค่าออกเป็นอะไร
แต่มันก็ยังดูไม่ค่อยช่วยอะไร เพราะ type ของ state ยังคงเป็น any และ return type ก็ยังเป็น void อยู่เลย งั้นเรามาลองเพิ่มรายละเอียดกันอีกสักหน่อย
ทีนี้กลับมาดูผลลัพธ์กันหน่อย สิ่งที่ได้คือ
คราวนี้ document ของเรามีการอธิบายถึงตัว parameter จากเดิมที่เป็น type any ตอนนี้มีการอธิบายออกมาในรูปแบบของ object ทั้งชื่อ key และ type ส่วนค่าที่ returm ออกมา จากเดิมที่เป็น void ก็เปลี่ยนเป็น boolean ตามที่เราได้เขียนไว้
และนอกจากนั้นในระหว่างที่เรากำลังพิมพ์เพื่อเรียกใช้งานฟังก์ชัน vscode นั้นก็มี popup คอยบอกว่า เราจะต้องกำหนดค่าอะไรลงไปบ้าง
และความดีงามอีกอย่างก็คือตัว vscode จะมี snippet โชว์ให้เราอีกด้วย
เท่านี้ก็ไม่ต้องเลื่อนไปเลื่อนมาเพื่อดูว่า object ที่เราจะส่งไปต้องมี property อะไรบ้าง
ลองเอามาเทียบระหว่างเขียน JSDoc และไม่เขียน
ระหว่าง function ที่มีการเขียน JSDoc และไม่มีการเขียน หน้าตาจะเป็นอย่างไร เราลองมาดูกัน
ก่อนเขียน JSDoc
หลังเขียน JSDoc
นี่เป็นเพียงการเขียน JSDoc แบบคร่าวๆเท่านั้น ยังมีลูกเล่นในการเขียน JSDoc อีกมากมาย ถ้าสนใจก็สามารถลองเข้าไปดูได้ที่ https://jsdoc.app/ ครับ
สุดท้ายนี้… JSDoc อาจจะเป็นเพียงแค่ตัวช่วยเพื่ออธิบายในสิ่งที่เราเขียนขึ้นมาเท่านั้น สิ่งหนึ่งที่เราต้องคำนึงถึงเสมอคือเพื่อนร่วมทีม การเขียนโค้ดโดยไม่คำนึงถึงผู้อื่น เช่น การตั้งชื่อตัวแปรหรือฟังก์ชัน อาจจะดูเป็นเรื่องเล็กน้อย แต่จริงๆแล้วมันเป็นเรื่องที่สำคัญมาก เพราะหากมีคนต้องมาดูแลหรือปรับปรุงโค้ดที่เราไม่ได้ให้ความใส่ใจกับเรื่องเล็กน้อยเหล่านี้แล้วล่ะก็อาจจะทำให้งานต้องล่าช้า หรือเลวร้ายที่สุดอาจจะต้องลบทิ้งแล้วเขียนใหม่กันเลยทีเดียว อย่าลืมใส่ใจเรื่องเล็กๆน้อยๆเหล่านี้กันด้วยน้าา 👻
