Naming Best Practices - Part 1

Become a Subscriber

Naming is a very important aspect to well-written code. Names are not just for our convenience, they are our primary tool for communicating the intent of our code. Communicating intent with our code should be our first priority.

When we or someone else has to read through the code to understand a name we used, then that name has failed to correctly communicate it’s intent. Same goes for having comments. If we have to comment the meaning of a variable or function, then it is still not properly communicating the intent.

Take for example the following

let bankAccount = BankAccount()
bankAccount.tran(a, accountTwo: b, am: am) // Transfer funds from Account One to Account Two

For starters we have a function called tran, single letter variables and a double letter variable which give us no indication of what they mean. Then we see that there is a comment next to it to let us know what’s actually going on. We could fix this all with descriptive names and we can even remove our comment!

Let’s start by making our function name more description.

bankAccount.transferFundsFromAccount(a, toAccount: b, amount: am)

We still know nothing about a, b, and what type of accounts they could be. Am also makes sense only in this context, if we were to use it somewhere else, it may not make sense.

For the sake of our example, let’s say that account a is a Savings Account and b is a Credit Account.

bankAccount.transferFundsFromAccount(savingsAccount, toAccount: creditAccount, amount: amountToTransfer)

This method is now more descriptive and we now have an idea of what type of accounts we are transferring money to.

Disinformation

Programmers can be very sinful people. We commit sins via code all the time, but one of the worst sins a programmer can commit is disinformation. Disinformation is writing code that does not mean what it says. Take for example

/* Returns users first, middle, and last name */
func fullName(user: User) -> String {
 return “\(user.firstName) \(user.lastName)”
}

We would expect this function to return a users full name, but we can see that it’s missing a users middle name.

Granted this is not the most serious of examples, but disinformation can cause for serious consequences if the expect behavior does not match up with the name of the function.

Pronounceable names

A name should be pronounceable. If someone has to make up a pronunciation for your variable, function, etc. then it’s intent is not clear. A variable named something like “PIDGW”, is not a good idea. How do we even being to pronounce this?

Prefixes

RIP NS Prefix! Prefixes should not be used in your code. They may make sense to you, there may even be a guide that explains what the prefixes mean, but someone would have to be aware of this guide and have to reference it to even understand what a variable or function may mean.

We’ve seen things such as “sz”Name used for null or zero-terminated string or “l”AccountNum used for long integers. There was/is an entire notation called Hungarian notation that gave many early developers a convention for naming practices. Naming is a very important aspect to well-written code.

Summary

  • Names are a primary tool for communicating intent of our code.
  • Names should be descriptive.
  • Comments are not necessary if the name correctly communicates intent.
  • Disinformation is writing code that does not mean what it says.
  • Names should be pronounceable.
  • Avoid using prefixes.

In the next article we will discuss more rules for naming our variables, functions, and more.