Naming variables, functions, classes, arguments, and packages is an art not everyone understands. Those who understand, live a technical debt-free life. But few simple pointers can help you reach this goal. While most of these will sound obvious but are not completely implemented by a lot of developers. Read ahead to crack the code for writing meaningful names.
Choosing good names takes time but saves more than it takes.
The names of variables, functions, classes should answer three broad questions:
- Why it exists
- What it does
- How it is used
var d; //does not reveal anything var daysSinceCreation; // clearly reveals what it stores var isModalOpen; // depicts the variable is a boolean const getUserID; // denotes a function or task
Hence, focus on the simplicity of the code rather than simplicity. If a variable requires a comment, it does not reveals its intent well.
Avoid names which leave false clues which might obscure the meaning of code. Treat it as an honourable human, it should say what it means and mean what it says.
- Don't name a group of accounts as
AccountListunless it is a list.
- Avoid two names with subtle differences like
Number-series naming like a1, a2, ...., an makes the code non-informative and does not reveals anything about the intention.
Another avoidable typing of naming is using noise words. Words like variable, NameString, Customer, does not reveal anything and so should be avoided.
Use words that are pronounceable so that others can use it for communication. This will enable better collaboration because "Programming is a Social Activity".
Imagine someone calling you to fix the bug and mentions using the function getmddh which gets month, date, day and hour for the post. Saying "get-M-D-D-H" is both frustrating and confusing, so rather just call it getPostTimeStamp.
Similarly names should be searchable. Single or double letter names are hard to search in a codebase. In this case Ctrl+Shift+F will no longer be at rescue and is such a bade case for giving meaningful names.
- Class and Object names should be a noun or noun phrase like AddressParser, WikiPage, and CustomerDetails.
- Method names should be a verb or verb phase like deleteUserEntry, getUserDetails and savePostData.
- Booleans should have prefix like "is" to communicate binary or 0-1 behaviour.
Sometimes variable names require additional data to give context to generic variable names like firstName, LastName, city, zipcode etc. In such a case adding a prefix like addrfirstName and addrLastName will denote it being a part of a larger Address class.
- Variables with shorter scope should have shorter name and vice-versa because ones with longer scope at used at multiple locations and should be descriptive.
- For classes/functions, the opposite is true because the longer the scope, easier should be the access for class/functions names. It should be short and crisp however for shorter scopes, longer and descriptive names can be helpful to reveal the intent.
Quoting from the book,
Any fool can write code a computer can understand, but it takes a good programmer to write code that humans can understand.
Head over to Part 2 of the series.