Why naming convention is a MUST for your development team

Guideline to set up good naming convention for your team

Mark
Mark
Sep 9, 2018 · 5 min read

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.

  1. Increase development time
    Developer understand the code by searching the class name, function name and variable name. If you have multiple naming format, like lbl, label, lab, it leads the developer spend energy to remember to name but not how to solve the problem.
  2. 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.
  3. Make the project structure more complex
    In some project, you may be able to find a class called GeneralManager or 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.

  1. Everyone has its own naming standard
    Everyone has its own development experience. Someone may use label as suffix, another may use lbl as suffix.
  2. Different popular naming standard in a single language
    Some languages has more than 1 popular naming standard, such as name_label or nameLabel.
  3. Multiple word can represent the same meaning
    Let’s use birthday as an example. You can name the var as birth, birthday or 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.

  1. 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.
  2. 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.
  3. 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 birth, birthday or dateOfBirth.
  4. 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.

  1. Project name
  2. File name
  3. Framework name
  4. API services
  5. Class name
  6. Configuration File
  7. Function name
  8. Variable
  9. 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

  1. 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 _lbl for UILabel and 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.
  2. 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.
  3. select an accurate and meaningful word
    You should always assume a new engineer who will read your code without your explanation.
  4. 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.

What next?

Now, we have explained everything about naming standard to you, you can follow the steps to start.

  1. List down what components you want to apply the naming standard.
  2. Research which naming standard is suitable your team.
  3. 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.
  4. Open a meeting and ask every team members to join
  5. Explain to them WHY you want to have a new standard and WHAT benefits will come to your project.
  6. Discuss about the standard you suggest and when to start the new naming standard
  7. Record down the discussed naming standard and upload to a place everyone can access
  8. 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.

Integrate Fastlane to your iOS Project

Mark

Written by

Mark

A Software Engineer

More From Medium

Also tagged Team Building

Related reads

Nick Moore
May 2, 2019 · 4 min read

47

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade