Clean code nói chung và naming convention nói riêng là một chủ để gây nhiều tranh cãi, mỗi tổ chức hoặc developer lại có một convention riêng trong đặt tên file, tên biến, tên hàm trong code và kể cả trong tài liệu.
“The ratio of time spent reading (code) versus writing is well over 10 to 1 … (therefore) making it easy to read makes it easier to write.”
— Robert C. Martin
Thống kê cho thấy trung bình một developer mất 75% thời gian cho việc đọc hiểu code, 20% sửa code có sẵn và chỉ có 5% là thực sự viết code mới thôi (nguồn)
Chúng ta không hề có một quy chuẩn chung trong việc đặt tên, mặc dù đều đồng ý với nhau rằng việc đặt tên là rất quan trọng trong lập trình. trong bài viết này tác giả xin phép trình bày 9 nguyên tắc đặt tên áp dụng cho mọi ngôn ngữ cũng như tình huống trong lập trình.
Định nghĩa
Trong khoa học máy tính, quy ước đặt tên (tiếng Anh: naming convention) là một tập hợp các quy tắc để chọn chuỗi kí tự được dùng cho các định danh biểu thị các biến, kiểu, hàm, và các thực thể khác trong mã nguồn và tài liệu.
— Wikipedia
Khó Khăn
Lựa chọn các quy ước đặt tên (và mức độ thực thi) thường là một vấn đề gây tranh cãi, với các phe phái giữ quan điểm của họ là tốt nhất và những cái khác là tệ nhất. Hơn thế, kể cả với các quy ước đặt tên đã biết và được xác định rõ ràng, một số tổ chức có thể không tuân thủ sự nhất quán, gây ra sự thiếu nhất quán và nhầm lẫn. Những thử thách này có thể trở nên trầm trọng nếu các quy tắc quy ước đặt tên không nhất quán nội bộ, tùy tiện, khó nhớ, hoặc có thể được xem là gánh nặng hơn là có lợi.
— Wikipedia
Vấn đề khó khăn nhất trong việc thống nhất quy tắc đặt tên có lẽ là mỗi người là có một bộ quy tắc riêng dựa trên trải nghiệm cá nhân của mình, thực sự việc thống nhất với nhau và đọc hiểu code của nhau là một thử thách khó nhằn.
Rule #1 — Ngữ Nghĩa Là Vua 👑
Đừng ưu tiên gắn gọn, hãy ưu tiên ngữ nghĩa
Theo tác giả đây là nguyên tắc quan trọng nhất, mọi thứ khác sẽ chẳng là gì nếu cái tên bạn chọn mơ hồ hay thậm chí là vô nghĩa.
😳 const users; 😎 const numberOfUsers; 😳 const friends; 😎 const friendsOfCurrentUser;
Thực tế các developer thường ưu tiên đặt tên ngắn gọn hơn là đầy đủ ý nghĩa, nhưng họ quên mất rằng code của mình sẽ được đọc bởi những người khác nữa, cho đến khi chúng ta đọc code do người khác viết chắc chắn những tên được đặt với đầy đủ ngữ nghĩa sẽ dễ đọc hơn nhiều so với những cái tên ngắn hơn nhưng mơ hồ. ví dụ với biến lưu số lượng users thì numberOfUsers sẽ rõ ràng hơn users và friendsOfCurrentUser sẽ rõ ràng hơn friends trong ngữ cảnh số lượng bạn bè của user hiện tại.
một trong những lỗi hay gặp phải đó là đặt tên biến quá chung chung như total count getData updateValue onClick tất nhiên trong một số trường hợp đó vẫn là những cái tên tốt nhưng đa phần là quá chung chung và không thể hiện đủ ngữ nghĩa của đối tượng được đặt tên. thay vào đó chúng ta có thể gắn thêm thông tin cho tên ví dụ như getUserData updateFormValue onAddItem.
Để đặt tên có ngữ nghĩa rõ ràng hơn bạn có thể tham khảo Naming cheetsheet với những nguyên tắc rõ ràng trong việc đặt tên như S-I-D hay A/HC/LC pattern chắc chắn không làm bạn thất vọng.
Rule #2 — Tính Nhất Quán 🚃
Chọn một từ cho một khái niệm — Sử dụng một khái niệm xuyên suốt hệ thống
fetchData() {...}
getData() {...}
retrieveData() {...}
Cả ba cái tên ở trên đều biểu thị chung một khái niệm và việc chúng ta sử dụng tên nào hoặc cả ba tên trên đều không ảnh hưởng tới ý nghĩa, nhưng để giữ được tính nhất quán chúng ta chỉ nên chọn một tên cho khái niệm này và sử dụng xuyên suốt cả hệ thống. Giả sử chúng ta chọn từ fetch để biểu thị khái niệm lấy data từ server về, thì ta phải giữ từ đó cho tất cả các function lấy data tương tự, ví dụ như fetchPermissions hay fetchUserDetails.
Rule #3 — Phân biệt Theo Ý nghĩa 🙌
Sử dụng cùng một từ cho một mục đích
Nếu gặp 2 từ cùng đại diện cho một ý nghĩa, hãy thử sử dụng cùng một từ xem. Đổi lại nếu là 2 ý nghĩa khác nhau nhưng lại sử dụng chung một từ để đại diện bạn nên đổi 1 trong 2 cái tên đi 😡
Theo bạn, 3 function dưới đây return gì? 😕
getUserDetails() {...}
getCurrentUserInfo() {...}
getriendData() {...}
Có gì khác biệt giữ details/info/data vậy?!
Nếu 3 thứ đó khác nhau thì rõ ràng là chúng ta cần 3 cái tên, nhưng nếu là chung interface thì chúng ta nên chọn 1 từ thôi để thể hiện kiểu dữ liệu đó.
Một ví dụ khác:
// Function in Class A
function add(x, y) {
return x + y;
}
// Function in Class B
function add(x) {
this.items.add(x);
}
Chúng ta có thể thấy 2 function cùng có tên là add nhưng lại mang 2 ý nghĩa khác nhau, hàm thứ nhất là cộng 2 số x và y, hàm thứ 2 là thêm một phần từ vào mảng items.Tất nhiên về ý nghĩa thì không sai nhưng chúng ta đã sử dụng 1 từ add cho 2 mục đích khác nhau, không dễ đọc chút nào.
Chúng ta có thể refactor lại như sau:
add(x, y) -> addNumbers(x, y)
add(x) -> insertItem(x)
Rule #4 — Tránh Encodings 😱
Tên biến không nên đi kèm với kiểu dữ liệu hoặc Encoding
string urlString; int numberOfMembersInt; Array<string> namesArray;
Thoạt nhìn những biến triên đây khá ổn và cũng dễ hiểu, nhưng hãy tưởng tượng chúng ta có nhiều biến như thế hơn với một hàm phức tạp hơn thực sự không hề dễ đọc, cũng như nếu đổi kiểu dự liệu hay encoding thì chúng ta phải đổi lại tên biến nữa.
Tên nên mang tính trừu tượng về đối tượng mà nó đại diện, thay vì mô tả thêm kiểu dữ liệu hay encoding.
Rule #5— Phát Âm Được 🙉
Viết là để đọc, không có lý do gì mà code bạn viết ra lại không thể đọc lên được
const lblFName; //first name label const nowTsMs; //now date timestemp since 1970 in milliseconds
Những tên biến trên đây đều rất khó để đọc được, đầu tiên là chúng ta sẽ khó nhớ được chúng, cũng như rất bất tiện trong việc trao đổi với nhau trong team. Không những thế, những tên không đọc được sẽ khó search, và với những dự án lớn thì seach code gần như là cách duy nhất đề đọc hiểu được codebase.
chúng ta có thể refactor lại đoạn code trên như sau:
const firstNameLabel; //first name label const nowTimestampMs; //now date timestemp since 1970 in milliseconds
Rule #6 — Hạn Chế Bày Tỏ Cảm xúc 😷
Nếu bạn muốn bày tỏ cảm xúc của mình, hãy đăng trạng thái lên mạng xã hội, không phải trong code
function killThemAll(); function whack(); function giveSomeLove()
Gì vậy các dev, kể cả bạn mới được crush tỏ tình hay bị bồ đã cũng không có ai quan tâm đâu, xin hãy giữ sự trong sáng của code và bỏ hết những cái tên cố tỏ ra bực bội hay cute đi.
Những người sau đọc code của bạn sẽ cảm thấy dễ chịu hơn nhiều đấy.
Rule #7 — Ưu Tiên Tên Tích Cực 😄
shouldNotShowIfDisabledIsFalse ✌️
isDisabled should become isEnabled
isUndefined should become isDefined
shouldNotShowScreen should become shouldShowScreen
avoidBroadcast should become doBroadcast
broadcastNotArrived() should become broadcastArrived({})
Không phải chuyện tâm linh đâu, con người sẽ dễ tiếp thu sự tích cực hên là sự tiêu cực nên một cách khoa học mà nói, hãy cố suy nghĩ và đặt tên theo hướng tích cực nếu có thể.
Rule #8 — Hạn Chế Helpers và Utils 🙄
NetworkHelper
RequestManager
HttpUtilsTất nhiên chương trình nào cũng sẽ có đầy những helpers hoặc utils, nhưng thẳng thắn với nhau đi rất nhiều trong số đó chỉ là vì bạn lười đặt tên và tổ chức code thôi đúng không. thay vì tạo một module mới hoặc class mới thì bạn tiện tay gọi nó là helper, nó tiện thật nhưng không tiện với người phải đọc lại đống bùi nhùi đấy.
Nếu đó đúng là helpers function cũng hãy tổ chức thành các cluster nhỏ hơn với các nhóm functions cùng chức năng chứ không phải một god objects với một đống hổ lốn các helpers đâu.
Rule #9— Luôn Tính Táo🤖
Characters are cheap, confusion is expansive
Không có bộ quy tắc nào là hoàn hảo, điều quan trọng là bạn phải luôn tính táo và luôn có ý thức giữ code mình luôn clean và dễ đọc.
Luôn nhớ rằng:
- Chúng ta KHÔNG phải người duy nhất đọc code
- Không ai quan tâm đến cảm xúc của bạn trong code dâu
- Code là để cho người đọc, không phải máy tính
- Đừng quên đọc lại code của mình
- Code làm sao cho dễ seach
Lời kết
Đặt tên chưa bao giờ là dễ cả, hy vọng với một vài gợi ý nêu trên chúng ta có thể có thể có một cái nhìn rõ ràng hơn về việc đặt tên cũng như thu nhặt thêm được những cách đặt tên trong dự án của mình sao cho code viết ra là dễ đọc nhất có thể. Theo kinh nghiệm của tác giả cách tốt nhất để học cách đặt tên là học từ Github, bạn có thể đọc code các repo lớn hoặc các PRs, và issues chắc chắn sẽ học hỏi được rất nhiều đấy.
Chúc bạn Naming tỉnh táo✌️ #cleancode #naming #convention
Uốn lười bảy lần trước khi nói sao không suy nghĩ bảy giây trước khi đặt tên?
— Minh Gì Đó
Bài viết gốc:
Naming cheatsheet: https://github.com/kettanaito/naming-cheatsheet#english-language
