How should name your application’s variable and functions?
Thou shalt use human language for yer variables and functions
Every coder in the world must be encounter at least one source code that has poorly named application variables. Poor naming in code is bad in various ways. It makes new coder or maintainer’s life miserable by taking their precious time to understand what certain variable means in that particular code. For example, look at this “simple” code:
public List<int[]> getThem() {
List<int[]> list1 = new ArrayList<int[]>();
for (int[] x : theList)
if (x[0] == 4)
list1.add(x);
return list1;
}Who is “them”? What is list1? Why only execute on x[0] == 4? See? It’s hard, isn’t it? Do you trust me if this is the code to get the marked board in the minesweeper game? (not actual code of minesweeper game, but, you got the point *wink*).
So, how to make your variable and function name better then? There are few things to make your code naming better:
Use Intention-Revealing Names
Just like our example before, the use of non-intention revealing names can be confusing to code readers that did not understand the context of the code beforehand, or even those who understood the context in the first place. So, how can you fix that mess? For that, look at the following:
const FLAGGED = 4;public List<int[]> getFlaggedCells() {
List<int[]> flaggedCells = new ArrayList<int[]>();
for (int[] cell : gameBoard)
if (cell[status] == FLAGGED)
flaggedCells.add(cell);
return flagged;
}
Compared to our example before, it is much easier to get what the code trying to do. When we make the intention explicit in the code, it will make your maintainer’s life much better.
Avoid Disinformation
Have you ever found a variable that looks like private productList and then it accessed like printf(productList ?? '') ? Yeah, that’s unlikely. But that kind of naming still exists out there. But pretend if you found that kind of code, you must be thinking, “Is productList a string, or a list?”. That kind of disinformation is harmful to the maintainability of your code.
Then, how can we fix this? If productList type is a list, you can use products or productList . If it is a string, you can name it product , or specifically, productName if it is a product name. That way, you can prevent misinterpretation of what a variable means.
Have Meaningful Distinction
So, you have code for few months, you running out of names for naming accounts but you need to name your variable. So what do you do? You set it to accnts . DON’T! In the future, that kind of naming will haunt you. When you make another module, and you call that problematic naming, you won’t know the name to call. Is it accounts or accnts ? Your auto-completer won’t know what name to pick, you won’t know what name to pick, and yer screwed up. Make each variable name distinct from each other, and if you cannot do that, at least you can give extra context to the name, i.e. accounts become parentCompanyAccounts , then others become childCompanyAccounts.
Use Pronounceable Names
As humans, we are good at words. And words are pronounceable. It would be a waste to not it for our advantage. Imagine this scenario: You have a bug in your code, and you need to ask for help from your senior programmer. The variable is genymdhms (stands for generation date in year, months, day, hours, minutes, seconds). You’ll say, “Hey, so why is this gee-nai-em-de-hms return null?”. You’ll look like an idiot. When you have the variable as generationTimestamp , it will be easier and you or others won’t look like idiots when asking about it.
Use Searchable Names
Single-letter names on constants will be a problem for your auto-completer to search, otherwise, MAX_PRODUCT_IN_LIST will be easier to get (and remember to!). The only exception to using a single-letter name is when it is used as a local variable. Though, if your function or method is getting larger, consider refactoring it to a more searchable name.
Avoid Mental Mapping
Code readers SHOULD NOT mentally translate certain names into other names that they already know. A common example of this is the letters i, j, and k inside a loop. This is because those single-letter names are traditional and commonly used in computer science classes. However, that is not recommended for another single-letter name. It is a bit dumb to choose the letter c just because a and b are used, right? Remember, clarity is king in programming!
Class, Method, and Variable Name
Classes and objects should have noun or noun phrase names like Customer, Products, StringParser, etc. The reason for this is because classes and objects will contain actions (functions). Because of that, functions or methods name should be a verb. That way, a class and function call be coherent and easy to understand. See that Company.addEmployee(employee) is easier to understand and read than Company.employee('John') .
Don’t Add Jokes in Your Variable Name
iiiiiiiiiis Boris!
Uuuh… Okay, so… When you use a joke for your variable name, it may seem fun for you. However, that also adds confusion to your new maintainer to read your code. For example, if you use boris as your email handler class name even, you won’t know what is. Is it a gateway? Is it Boris himself? Or what? You have no idea until you go deep into that module (which you have failed to give clarity to new coder). So don’t do it!
Use Consistent Wording
You have use the word get for adding items across your code. Good work! However, you then decide to use the word add for “consistency” whether it is in the same context or not. This will cause the word get to not be consistent anymore and causing confusion, which we are trying to avoid in the first place.
It is okay to follow the “One word per concept” rule. While you could end up with many classes that have to get method. As long as the parameter lists and return values of the various add methods are semantically equivalent, all is well. If you found out that it is a different get type, you can use other synonyms such as fetch, retrieve, or download even to make it distinct.
Don’t Abbreviate Unless Necessary
Imagine your application is called “My Happy Restaurant”, you may be tempted to prefix every class with MHR . However, don't do this! You are making your auto-completer working against you. When you type MHR, there will be a googol suggestion for you. Also, while shorter names are generally better than longer ones, you also don’t want to make it too short that it would confuse you. Auto-completer exist for that specific reason :)
Learn Code Standard
Learning code standards also will help you to name your variable and functions better. By using standards, you also make your code more or less clearer than before. Such example of code standards is CSS’ BEM, PHP’s PSR, Flutter’s Style Guide, and etc.
Conclusion
Choosing a name for your variable is hard and confusing sometimes, it requires good descriptive skills and a shared cultural background. You also may be afraid or in fear of other coders' rejection when you change certain naming in the code. Truthfully, it doesn’t matter as coders usually don’t remember names we wrote in the code. It’s okay, as long as it improves readability, it will be accepted. And also, it may be a hassle to change certain naming in short term, but it will be paid off in the long run.
Credit: This story is heavily inspired from “Clean Code: A Handbook of Agile Software Craftsmanship” book by Robert C. Martin. You can buy the book here