ตั้งชื่อ variable ยังไง ให้คนอื่นรู้เรื่อง (Meaningful Names)

จากคำบอกเล่าจากโปรแกรมเมอร์หลากหลายคน รวมถึงจากประสบการ์ณตรงของผู้เขียนเองด้วย สิ่งที่ยากที่สุดไม่ใช้การเขียนอัลกอริทึมยากๆ แต่!!! กลับเป็นการตั้งชื่อตัวแปร function และอื่น ๆ อีกมากมาย (แนบหลักฐานด้านล่างว่าเราไม่ได้คิดไปเองคนเดียว)

https://josephfitzsimmons.com/the-hardest-problem-in-programming-is-what-to-name-your-variables-and-functions/

สิ่งหลายๆคนก็สงสัยว่า เอ๊ะ ตั้งชื่อตัวแปรมันจะยากอะไรล่ะ ดูไม่ต้องใช้ความคิดอะไรเยอะขนาดนั้นนี่นา แต่หารู้ไม่ว่าหากเราตั้งชื่อตัวแปรที่ไม่ดีและไม่สื่อความหมาย ทำให้คนอื่นๆ ที่มาแก้ไข code ของเราต่ออาจจะใช้เวลา 1 วันเต็มๆ (หรืออีกหลายวัน) !!!ในการอ่าน code ของเราให้รู้เรื่องเลยก็ว่าได้ เพิ่มความซับซ้อนของระบบไปอีก

จากประสบการณ์ตรง ที่เจอมาเช่น ตัวแปรสำหรับเป็นข้อมูลของ user แต่ตั้งชื่อเป็น data และ ตัวแปรสำหรับเก็บข้อมูลของ company ตั้งชื่อเป็น data_2 ที่นี้พอเราต้องมาเขียนต่อ งงเป็นไก่ตาแตกเลยทีเดียวว่าแต่ละตัวแปรทำหน้าที่อะไรกันแน่ ต้องไปไล่ดู context อื่นๆ เอาทำให้เสียเวลาไปพอสมควร

บทความนี้เลยจะมากล่าวถึงการตั้งชื่อตัวแปรอย่างไรให้ สื่อความหมายและคนอื่นสามารถเข้าใจ code ของเราได้มากขึ้น โดยจะมีหลักการ ดังนี้

1. ใช้คำที่สื่อความหมายชัดเจน

ควรใช้คำที่สามารถบ่งบอกความหมายของตัวแปรนั้นได้ชัดเจน โดยที่ไม่ต้องใส่ comment เพิ่มเติมในโค้ดเช่น

int d; // elapsed time in days

จากตัวอย่างข้างบน d ไม่ได้สื่อถึงอะไรเลย หากมี Developer คนอื่นๆ มาอ่านจะไม่เข้าใจว่าค่านี้หมายถึงอะไร ถ้าเราไม่ได้ใส่ comment เพิ่มเติม ดังนั้นเราควรจะตั้งชื่อตัวแปรว่า

int elapsedTimeInDays;

เมื่อเราตั้งชื่อให้สื่อความหมายมากขึ้น ผู้อ่านจะเข้าใจได้ทันทีว่าตัวแปรนี้หมายถึง ตัวแปรที่เก็บค่าว่าเวลาผ่านไปกี่วัน

แต่ทั้งนี้ทั้งนั้นความยากของหัวข้อนี้คือ คลังคำศัพท์ในหัวเราต้องมีเยอะพอสมควรและคำศัพท์ที่เลือกมาใช้ ไม่ใช่แค่ความหมายถูกต้อง แต่ยังต้องคำนึงถึงศัพท์ที่ทาง Business ใช้งานจริงอีกด้วยค่ะ

2. หลีกเลี่ยงคำที่เป็น Datatypes

การตั้งชื่อตัวแปรไม่จำเป็นใส่ datatypes ของตัวแปรนั้นๆไปด้วย เช่น

String nameString
Int salaryInt

เพราะว่ามีการกำหนด datatypes ของตัวแปรนั้นๆไว้อยู่แล้ว ไม่จำเป็นต้องใส่เพิ่มเติม เพิ่มความซับซ้อนในการอ่านค่ะ เราควรจะตั้งชื่อเป็น

String name
Int salary

3. ตั้งชื่อให้มีความแตกต่างกันอย่างชัดเจน

เมื่อมีตัวแปรสองตัวหรือหลายๆตัวที่สื่อความหมายแตกต่างกัน ควรที่จะตั้งชื่อทั้งสองตัวแปรให้มีความแตกต่างกันอย่างชัดเจน ไม่ควรใช้คำที่มีความหมายเดียวกัน เช่น

[]String ProductInfo
[]String ProductData

ตัวอย่างด้านบนจะเป็นว่าเทียบไม่รู้เลยว่าตัวแปรทั้งสองตัวนี้เก็บข้อมูลแตกต่างกันอย่างไร

หรือถ้าเราตั้งชื่อ function ที่ใกล้เคียงกันเช่น

void getActiveAccounts()
void getActiveAccountsInfo()

จากตัวอย่างด้านบน ถ้าเราเป็น Developer มาอ่าน แล้วต้องการเรียกข้อมูลของ account ที่กำลัง active อยู่ เราจะเลือกเรียก function ไหนคะ แน่นอนว่าส่วนใหญ่สับสนแน่ๆว่าควรจะใช้ function ไหน เพิ่มความลำบากให้เหล่า Developer อีกต้องไปไล่โค้ดดูว่า function ไหนให้ข้อมูลที่เราต้องการกันแน่

จากตัวอย่างด้านบนน่าจะพอเห็นภาพกันแล้วว่าถ้าเราไม่ตั้งชื่อตัวแปรให้มีความแตกต่างกัน คนอ่านอาจเกิดการสับสนในการเรียกใช้งานตัวแปรต่างๆได้ค่ะ

4. ใช้คำที่สามารถออกเสียง(Pronounceable)ได้

เราต้องมั่นใจว่าชื่อตัวแปรที่เราตั้งขึ้นมา คนทั่วไปต้องสามารถออกเสียงได้ ตัวอย่างถ้าเราตั้งชื่อตัวแปรที่ออกเสียงไม่ได้จะเป็นแบบนี้

private Date genymdhms;
private Date modymdhms;

ความลำบากของการตั้งชื่อแบบนี้คือ เวลามีการประชุม หรือ discuss เกี่ยวกับ scope นั้นๆ เราจะไม่สามารถออกเสียงตัวแปรนั้นได้ หรือ ออกเสียงเป็น จี-อี-เอ็น-วาย … แบบนี้สร้างความลำบากให้กับคนพูดและคนฟังอยากมาก เราจึงควรตั้งชื่อว่า

private Date generationTimeStamp;
private Date modificationTimestamp;

แบบตัวอย่างด้านบนจะง่ายต่อการออกเสียงและพูดถึงมากกว่า

5.ตั้งชื่อให้สามารถค้นหาได้ง่าย (Searchable)

หากเป็นตัวแปรที่มีความสำคัญ เราควรตั้งชื่อให้สามารถค้นหาได้ง่าย ไม่ควรตั้งด้วยตัวอักษรเดี่ยวๆ (เช่น i, j) หรือ ตัวเลข เช่น

Int j;
String 15;

เวลาที่ Developer ค้นหาใน editor จะค้นหาลำบากและตัวแปรยังไม่สื่อความหมายอะไรอีกด้วย เราควรตั้งเป็น

Int MAX_CLASSES_PER_STUDENT;
String studentName;

6. ใช้คำให้มีความสม่ำเสมอกัน (Consistency)

เวลาที่เราทำโปรเจคที่ใหญ่ๆ และมี developer หลายๆ คนเขียน เชื่อว่าทุกคนต้องเคยเจอตัวแปรหรือ method ที่ทำงานเหมือนกัน แต่มีหลากหลายชื่อเหลือเกิน ตัวอย่างเช่น การเรียกดูข้อมูลจะเจอทั้ง FetchValue หรือ GetValue หรือ RetrieveValue
การแก้ไขข้อมูลจะเจอ EditValue หรือ UpdateValue ซึ่งทั้งหมดนี้ไม่มีถูกหรือผิด แต่ควรใช้ให้เหมือนกัน ถ้าจะสื่อถึงการเรียกดูข้อมูลใช้ GetValue ทั้งโปรเจคก็ควรใช้ GetValue ให้เหมือนกันไปเลย ขึ้นอยู่กับข้อตกลงกันในทีม

7. ตั้งชื่อจาก Solution vs Problem Domain Names

ก่อนเข้าเนื้อหาเกริ่นก่อนว่า Solution Domain Names คือ พวกชื่อ algorithm หรือพวก design pattern ส่วน Problem Domain Names คือ ชื่อที่มีความเป็น business มากขึ้น จากปัญหานั้นๆ
ซึ่งส่วนใหญ่แล้วคนที่มาอ่านโค้ดของจะเป็น Developer ซะมากกว่า ดังนั้นเราควรตั้งชื่อตัวแปรจาก Solution Domain Names ก่อนที่เลือกตั้งชื่อตัวแปรจาก Problem Domain Names

8. เพิ่ม Context เข้าไปในการตั้งชื่อ

ถ้าตั้งชื่อตามหลักข้อข้างต้นที่กล่าวไปแล้ว ชื่อหนึ่งชื่อควรจะสื่อความหมายได้ชัดเจน แต่จะมีกรณียกเว้นบางอย่างที่เราควรเติมบริบทเข้าไปในชื่อตัวแปรด้วย เช่น ชื่อตัวแปร “State” ซึ่งอาจหมายถึงชื่อของ State นั้นๆ หรือ ที่อยู่ของ State นั้นๆ ก็ได้ ดังนั้นเราควรเติม “stateName” สื่อถึงชื่อของ State นั้นๆ และ “stateAddress” สื่อถึงที่อยู่ของ State จะทำให้ผู้อ่านเข้าใจมากขึ้นว่าเราต้องการจะสื่อถึงข้อไหนค่ะ

ตัวอย่างแย่ๆ ที่เคยเจอมาก็คือ

1. ชื่อบอกว่าเป็นชนิด boolean เช่น isApproved แต่ค่ากับเก็บเป็นตัวเลขหรืออื่นๆ
2. ชื่อและชนิดของตัวแปรขัดแย้งกัน เช่น String isAvailable
3. ชื่อและ comment ของตัวแปรไม่ไปด้วยกัน
4. ชื่อตัวแปรเป็นเอกพจน์ แต่มีค่าเป็นพหูพจน์ เช่น user แต่ค่าคือ list ของ user
5. ชื่อตัวแปรเป็นพหูพจน์ แต่มีค่าเป็นเอกพจน์ เช่น usersแต่ค่าคือ user คนเดียว
6. ชื่อ method กับค่าที่ return ไม่ไปด้วยกัน เช่น method setValue แต่ return ค่าออกมา

สรุป

การตั้งชื่อตัวแปรเป็นหัวใจสำคัญหนึ่งของการเขียนโค้ดอย่างมาก เพราะในหนึ่งโปรเจคเป็นไปได้น้อยมากที่เราจะเป็น Developer คนเดียวในโปรเจคนั้นๆ แน่นอนว่าจะต้องมี Developer คนอื่นๆ มา maintanace ต่อ หรือแก้ไขโค้ดของเราแน่ๆ การตั้งชื่อที่ดีจะทำให้ง่ายต่อการ implement และ maintain มากขึ้นและยังแสดงให้เห็นถึงความใส่ใจต่อผู้อื่นด้วย
ซึ่งความยากของการตั้งชื่อตามความคิดเห็นของผู้เขียน ก็คือ คำศัพท์ที่เกี่ยวข้องกับ Domain นั้นๆ ซึ่งเราต้องเรียนรู้ศัพท์ใหม่ๆ ที่ไม่เพียงแค่เปิด dictionary เท่านั้น ยังต้องเป็นศัพท์เฉพาะทางที่เกี่ยวข้องกับ business นั้นโดยตรงจริงๆ อีกด้วยค่ะ และ

อย่างสุดท้ายที่อยากจะฝากก็คือ หลักการข้างบนทั้งหมดอาจจะไม่ได้เป็นหลักการตายตัวมากหนัก หลักๆ แล้วเราควรที่จะสื่อสารกับทีม หรือทำความเข้าใจให้ตรงกันว่าการตั้งชื่อตัวแปรในโปรเจค จะมีหลักการแบบไหน แล้วให้คนในทีม follow ตามจะดีกว่า

References

Naming Conventions From Uncle Bob's Clean Code Philosophy - DZone DevOps

Clean code 101 — Meaningful names and functions

Coding like Shakespeare: Practical Function Naming Conventions

หนังสือ Clean Code: A Handbook of Agile Software Craftsmanship