Clean code — Name matters

A good naming convention is one of the most important things in software engineering. In our work, we name a lot of things. We name classes, functions, variables, directories. Sometimes we will be asked to rename our method and sometimes we will be proposing new names. Naming thing is one of the most essential skills of every developer.

1. Give your names intentions

Name of class, function, variable should inform why was created, what do and how is used. If you need to add a comment above your variable you probably didn’t precise your intentions enough. Choosing the right name is a good investment so take your time. Asking your colleagues for help is a good idea. Remember you are not the only one who will be working with this code.

Bad:

public int $f_cnt; // friends count

Good:

public int $friendsCount;

Variable name f_cnt don’t inform us strictly what kind of information keeps inside. We have to guess or dig deeper into code to find the information we are looking for.

Bad:

public function process(array $u, $a = 18): array
{
    $results = [];
    foreach ($u as $i) {
        if ($i['a'] >= $a) {
            $results[] = $i['id'];
        }
    }

    return $results;
}

As you see this code isn’t complicated. It has only one array iteration and one conditional statement but can you deduce what this code does? The problem here is not code complexity but its secretiveness. Names of variables, array keys, and function properties are hiding important information from us. Let’s see at refactored code.

Good:

public function getAdultUsersIds(array $usersList, $adultAge = 18): array
{
    $adultUsersIds = [];
    foreach ($usersList as $user) {
        if ($user['age'] >= $adultAge) {
            $adultUsersIds[] = $user['id'];
        }
    }

    return $adultUsersIds;
}

Better immediately. We can now deduce what method does just by reading the name.

2. Avoiding desinformation

As programmers, we should avoid every disinformation in our code base. We should avoid suggesting incorrect variable type when choosing a name. Variable $account isn’t a good decision when keeps an array of Account class instances. Name $account tells us that we should expect an instance of Account class inside. Look at the example below.

Bad:

var_dump($account);
array(3) {
  [0]=>
  object(Account)#1 (1) {
    ["id"]=>
    int(1)
  }
  [1]=>
  object(Account)#2 (1) {
    ["id"]=>
    int(2)
  }
  [2]=>
  object(Account)#3 (1) {
    ["id"]=>
    int(3)
  }
}

Good:

var_dump($account);
object(Account)#1 (1) {
  ["id"]=>
  int(1)
}

Another bad habit is creating names that are very similar to each other. You will go mad every time you will need to find a difference between DailyNewCustomersOnlineDepositsReportHandler and DailyNewCustomersOfflineDepositsReportHandler

3. Create clear differences

We should avoid creating names that are very similar to each other. Let’s say we have Client class in our application and then we are creating another two: ClientInfo and ClientData. Imagine your colleague is making a code review for your pull request. Will he be able to see the differences between these classes? Words like info and data don’t add any new pieces of information.

We should add names in our application that allows the reader to see the clear difference between them.

4. Create names that can be pronaunced

If we can’t pronounce words we can’t discuss code where they were used. This is important because programming is a social activity. We are using classes, variables, method names in meetings, talking over lunch, and coffee breaks.

5. Use names that can be easily found

It’s easy to find all usages of method sendRegistrationEmail using IDE search engine. It will be harder if the same method would be called se. In the search results, we will have every usage of combined letters se: user, asset. Short names are usually better than longer but length should depend on the size of range. If variable or constant can be seen or used in a couple of places it’s very important to use a name that can be easily found.

6. Classes names

Classes names should be nouns like: Product, PasswordEncoder, Request. We should avoid words like: Service, Manager, Info, Data, Processor. often adding the word service leads to the creation of a class that is a garbage for functionality. In my life a saw a lot of CustomerService which could add customer to database, send email to customer and check if customer paid for order. Classes names shouldn’t be verbs.

7. Methods names

Methods should be named as verbs: save, registerUser, sendSms. Accessing and predictions methods should have names based on name of the property with prefix get, set, or is

8. Don’t be funny

At least in your code. It’s funny to name a command which drops database LeeroyJenkinsCommand but what if the new programmer will don’t know the origin of this name? :)

9. Adding a meaningful context

Imagine that you see in code variables street, postalCode, state, city. If these names are grouped in a class named Address everything is obvious for us. When names are put in the right context through precise naming of class or method you don’t need to add any prefixes. But sometimes this is your last chance to increase the readability of your code. Imagine the same variable state but this time it isn’t used inside Address class. We have to guess what this variable is representing. Maybe it is a state of the user (active/inactive), maybe state of order? Sometimes adding a prefix is a good choice but it strictly depends on the context in which the given name was placed.

Bad:

class Address {
    public $addressStreet;
    public $addressCity;
    public $addressFlatNumber;
    public $addressPostalCode;
}

Good:

class Address {
    public $street;
    public $city;
    public $flatNumber;
    public $postalCode;
}

Post scriptum: This article is highly inspired by the amazing book “Clean Code” written by Robert C. Martin. If you want to learn more about the topic discussed in the article I strongly encourage you to read it.