อ่าน code ง่ายขึ้นด้วย variable type annotation & Docstring
source code ที่ดี ไม่ใช่แค่ทำงานลื่นไหล ไม่ติดขัด แต่ยังต้องเขียนให้คนอื่นอ่านรู้เรื่อง เข้าใจง่ายๆ ด้วย ไม่อย่างนั้นก็ถือว่าเป็น spaghetti code ที่แก้ทีก็ลำบากที กว่าจะเข้าใจว่าต้องปรับอะไรตรงไหน
blog นี้เลยอยากจะเล่าถึงสองสิ่งง่ายๆ ที่เราทำได้ทันที เพื่อให้ code มีคุณภาพมากขึ้นฮะ ตามที่หลายๆ คนเคยได้ยินจากคนรู้จักหรือ blog อื่นๆ ว่า ถ้าเราทำให้ code มันอธิบายตัวมันเองได้ ก็จะทุ่นเวลาเขียน document ไปเยอะทีเดียวเชียว
Variable type annotation
ทุกคนน่าจะเขียน function และ control flow structure กันเป็นอยู่แล้วเนอะ ทีนี้ Variable type annotation หรือเรียกอีกอย่างว่า "Type hints" เนี่ยมีส่วนช่วยเราเวลาเขียนพวกนั้นว่าตัวแปรที่เราจะใช้มันมี type เป็นอะไร จะได้เก็ทง่ายขึ้น แล้วเขียนได้ไวขึ้นนั้นเองฮะ
Type annotation มีเขียนไว้ใน PEP (Python Enhancement Proposals) ซึ่งเป็น guideline เพื่อเขียน Python ได้อย่างมีประสิทธิภาพ และคุณภาพฮะ
Type annotation เนี่ย ไม่มีผลอะไรกับการ run program เลยนะ เขียนไปก็ไม่ช่วยให้ program run ผ่าน ไร้ bug แต่ประการใด แต่มันช่วยให้ developer ทำงานง่ายขึ้น เพราะเขียนไปแล้วว่าตรงนี้ใช้งานแบบไหน ไม่ต้องเสียเวลามาบอกกล่าวซ้ำซากฮะ
สมมติว่าเรามี function ตัวนึง ทีรับ argument สองตัว คือ num และ text อ่านแค่ชื่อก็เดาได้แล้วใช่มั้ยฮะว่า มันจะต้องเป็น integer กับ string แน่ๆ แค่นี้หมูๆ
แต่ถ้าเกิดว่า มันมี argument แปะชื่อว่า unit ขึ้นมาล่ะ เอ มันควรเป็นอะไรดีนะ integer ก็ได้เพราะ unit หมายถึงจำนวนหน่วย คิดอีกที เป็น string ก็ได้อีก อย่างเช่น "centimetre" หรือ "boxes"
ยกตัวอย่างให้เห็นภาพขึ้น ให้ encryption function มาแบบนี้
argument มีสองตัว คือ text อันนี้ string ชัดเจน แต่ offset คืออะไรอ่ะ แล้ว function นี้ส่งค่ากลับเป็นอะไร ค่อนข้างเข้าใจยากอยู่ใช่มั้ยฮะ
ไหนลองเขียนเป็นแบบนี้ซิ
แบบนี้แหละ เรียกว่า variable type annotation ทำให้อ่านเข้าใจง่ายขึ้นเยอะเลยฮะ
ทีนี้ ตอนเรากำลังเขียนเรียก function เราจะเห็น IDE มันช่วยแสดง argument ที่ function นี้ต้องการแบบนี้เลย
ต่อไปนี้ คือ ตัวอย่างการใช้ annotation ในแต่ละสถานการณ์ฮะ
Primitive types
Primitive types คือพวก int, float, bool, และ str เราใช้พวกนี้บ่อยสุด และเป็นพื้นฐานสุดแล้วล่ะฮะ
ก็แค่เติม colon : แล้วตามด้วย variable type ส่วน Return type ก็วางไว้หลังเครื่องหมาย ->
Default value
บางทีเราก็ต้องการให้มันมี default value หรือค่าเริ่มต้นให้เลย กำหนดด้วยเครื่องหมาย = ฮะ
ตัวแปรนี้มีหลาย type
ถ้าใช้ python 3.10 อยู่สามารถเขียน type แล้วคั่นด้วย pipe ( | ) ได้เลยฮะ เพื่อบอกว่าตัวแปรนี้นะ สามารถเป็น type ไหนได้บ้าง
แต่ถ้า version ต่ำกว่านั้น สามารถใช้ typing.Union module แทนได้ฮะ
สำหรับ typing module เข้าไปอ่านเพิ่มเติมตามลิงก์ด้านล่างได้ฮะ
Collection type
ถ้า argument เป็นพวก list, tuple, set แนวๆ นี้ เราใช้วงเล็บเหลี่ยม [] กำหนดตัวแปรข้างในได้ฮะ แบบนี้
Control flow variable
ถ้าเราจะเขียน loop แล้ว ต้องการประกาศประเภทตัวแปร เราไม่สามารถใช้ : ตอนประกาศ loop ได้นะฮะ เราต้องประกาศประเภทตัวแปรก่อน loop ฮะ หลังจากนั้น ก็จะสามารถใช้ auto-complete เติม attribute ของตัวแปรนั้นได้
unpack ก็เช่นเดียวกันฮะ unpack คือ การเขียน shorthand เพื่อแกะ collection ออกมาแล้ว assign ค่าลงตัวแปรแยกกัน เราก็ต้องประกาศประเภทตัวแปรก่อน unpack ฮะ
ตรงส่วนนี้ ผมได้ความรู้มาจาก stackoverflow อันนี้ https://stackoverflow.com/a/41641489.
Docstring
เอาล่ะ มาถึง docstring กันแล้ว
docstring เป็นเหมือนคำบรรยายใต้ function อธิบายว่า function นี้ทำอะไร รับอะไร ส่งค่าอะไรกลับไปบ้าง และมันก็ยังถูกเขียนไว้ใน PEP เหมือนกันฮะ
ถ้าใช้ IDE สมัยใหม่ เช่น VSCode มันมี intellisense ที่ช่วยเราเติม auto-completion ให้ ผมก็อยากแนะนำ plugin สำหรับ VSCode ที่ช่วยสร้าง docstring แล้วเราก็แค่เติมที่เหลือไป แล้วก็เสร็จเลย
plugin ตัวนี้มีชื่อว่า "Docstring" ที่อๆ งี้แหละฮะ
พอติดตั้ง plugin แล้ว อยากจะใช้งาน ก็แค่พิมพ์ """ มันก็จะมี submenu มาให้พร้อม
หรือจะเรียกใช้ ผ่าน palette ( cmd + shift + P) ก็ได้เหมือนกันนะ
เมื่อเราเขียน docstring ให้กับ function แล้ว ตอนเราจะเรียก function นั้น แค่พิมพ์ชื่อ ตัว IDE ก็จะเด้ง popup แสดง docstring มาตามที่เราเขียนเลยฮะ สะดวก รวดเร็วดีจริงๆ
มีให้ปรับแต่งตั้งค่าที่หน้า Settings
แล้วก็มี docstring format ให้เลือกหลายแบบด้วย
ผมรวบรวม format ของ docstring มาเป็นตัวอย่างทุกแบบตามข้างล่างนี้แล้วฮะ