Why naming convention is a MUST for your development team
Guideline to set up good naming convention for your team
Naming convention is a popular topic for software development. Most of the engineers spend time to discuss what standard we should follow, which naming convention standard should be used in their team. However, not much people focus on WHY we need naming convention.
Problems if you don’t have a good naming convention
A bad naming convention standard or without standard can lead the following issue.
- Increase development time
Developer understand the code by searching the class name, function name and variable name. If you have multiple naming format, like
lab, it leads the developer spend energy to remember to name but not how to solve the problem.
- Turn down engineer motivation
Engineer is human. Human is good to maintain only 1 standard at a time. If there are different naming styles in the project, it keeps to distribute the engineer concentration. From time to time, engineer doesn’t want to work on a project which is hard to understand the code.
- Make the project structure more complex
In some project, you may be able to find a class called
AppManager. Those unclear naming will guide the engineer to write all the code in there. Eventually, those class will become a god class and no one can touch that.
But, why poor naming convention or multiple standard still happen in lots of projects?
Why we have multiple or poor naming standard in the project?
We can summarise the reasons as below.
- Everyone has its own naming standard
Everyone has its own development experience. Someone may use
labelas suffix, another may use
- Different popular naming standard in a single language
Some languages has more than 1 popular naming standard, such as
- Multiple word can represent the same meaning
Let’s use birthday as an example. You can name the var as
dateOfBirth. It really depends on which words you choose and this problem are one of the troubles case in our project because you may believe others are using the same word as you.
- No merge request/ pull request
It relates to the team practise and culture. It is very easy to implement the hot fix to the project if no merge request/ pull request is required in the team.
- No guideline and standard to follow
If there are not documentation (yes, we need a documentation and update that if needed) to record down what is the naming standard rules, engineer can only following the naming standard in the project.
- Buy time for development
In stead to understand multiple standards, the alternative way is to ignore the origins standard, use your own standard for the project.
- Lack of experience to work in a large scale project
If you keep working with yourself or 1–2 engineer. You won’t find any big problems in your project. The worst case is your project has 2 different standards.
However, you will find this is a very serious problem if you team size more than 5 to 6 people. You will face around 3–4 standards. In this case, engineers will spend energy to argue which standard are the BEST and don’t focus on how to solve the problem.
- Without communication
I guess I don’t need to explain this point.
So, how can we implement a single and acceptable naming standard in your team?
What you should pay attention when you want to introduce a new naming convention to your team
When you try to introduce an new naming standard or updated standard, it should always pay attention how this impact to your team.
- Only try to apply the standard in part of the new code
If we update all of the code in the project, it will have a very big change. It is a dragons action if your project don’t have a complete automation test. You also need to update your unit test if you have that. We really don’t want to see more bugs comes out since we update the naming of the variable. A whole change should only be applied when your team has the consensus after implemented the the new naming standard a period of time.
- Open discussion for the naming
Gather all the team members when you want to custom a new naming standard for the project. Explain to them what is the benefits and drawbacks after implement the new naming standards. And then comes up a naming standard together.
- Keep communicate to others when you have new naming standard or wording
When you name a new structure file like
validator, which doesn’t exist in your project before, tell other what this is. Also, let other knows you want to use
- Record down the naming standards rules and update the documentation
After comes up a naming standard, it should record down to somewhere and everyone can access that. Remember to update the doc if there is some updates.
Which project component should have naming standard?
The answer is ALL. It should have a naming standard if your services or files will be used by other parties.
It lists down the common components.
- Project name
- File name
- Framework name
- API services
- Class name
- Configuration File
- Function name
- Translation file string key
What is the best naming standard rules
The basic concepts of naming method are easy to understand, follow and maintain. Most comment practises are
- append the prefix or suffix to the name
This is the common rules, you can create a list of prefix or suffix to the needed file, like
k_for the constant value. For the configuration file, we normally use the current date and time as the unique indicator for each of the file.
- use well-known and popular naming standard in the community
It always use the popular naming standard, such as Camel case (
dateOfBirth), snake case (
date_of_birth) and kebab case (
date-of-birth) are the most common and well defined standard. Don’t design your own standard.
- select an accurate and meaningful word
You should always assume a new engineer who will read your code without your explanation.
- follow the Grammar
If you name the var beginning with noun, it should keep using noun instead of using word or adj. It leads multiple standards.
Now, we have explained everything about naming standard to you, you can follow the steps to start.
- List down what components you want to apply the naming standard.
- Research which naming standard is suitable your team.
- Find some code in your project, update the code by using the new naming standard. The example should be able to demonstrate how the new naming standard improve your project.
- Open a meeting and ask every team members to join
- Explain to them WHY you want to have a new standard and WHAT benefits will come to your project.
- Discuss about the standard you suggest and when to start the new naming standard
- Record down the discussed naming standard and upload to a place everyone can access
- Apply to the project and keep review
Please give me a clap or share this post if you enjoy.
The following is my another interesting topics.