Clean code : Naming best practices

What’s in a name? “A rose by any other name would smell as sweet” is a famous quote from William Shakespeare’s classic Romeo and Juliet, but when doing software development name matters in fact it matters a lot in programming and coding.

When you ask software developer where they spend most of their time they will answer coding but reality is about 75% of time developer spends for understanding code. When you try to read the code then in general you will understand that naming of variables, classes and methods are the key reason why your code is difficult to read and understand.

Source: https://blog.codinghorror.com/when-understanding-means-rewriting/

Choosing good names takes time but saves more than it takes. So take care with your names and change them when you find better ones. Everyone who reads your code (including you) will be happier if you do.

Here are some naming best practices to follow which will make the code easy to read and understand. I have got this practices from the book “Clean code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin, I highly recommend everyone to go through this book.

Use Intention reveling names

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. By choosing good names it becomes much easier to understand the code.

You might be saying that but I don’t know what could be the best name for the class, variable or function, idea here is to choose the least worst name which provides maximum information on what are the intentions. Finally, do not hesitate to rename them as you learn more about the problem or you evolve your method with additional functionality.

Names should continually evolve and it should always change (for better).

# Dirty Code int n; # number of records 
# Clean Code number_of_records;
# Dirty Code Device d (or dev) = new Device();
#Clean Code Device device = new Device();
or based on context
Device device_to_register = new Device()

Make meaningful distinction

Programmers create problems for themselves when they write code solely to satisfy a compiler or interpreter.

As we create multiple objects or multiple classes to refer same thing we are tempted to give them some name in arbitrary way. Imagine that you have a User class. If you have another called UserInfo, UserObjector UserData, you have made the names different without making them mean anything different.

Similarly in method names if we have an application and there are methods such as getDeviceInfo, getDevice or getDeviceDetails it becomes extremely difficult for programmers to know the difference and call the right method.

Pick One word per concept

Pick one word for a concept and stick with it. For instance, it’s confusing to have fetch, retrieve and get or delete, purge and destroy as equivalent methods of different classes.

fetchUser() {...}
getDevice() {...}
retrieveEmployee() {...}

As we can see in above example these all functions are in single application but might be written by different programmer, in general it does the same thing of getting some information out of the class. Ideally, we should stick with one convention out of three and stick with it to make programmers life easy.

Likewise its also confusing to have manager, driver, processor in same code base unless there is subtle difference between their role.

Class names and method names

Classes and objects should have noun or noun phrase names like User, Alarm, Device, and AddressParser.Class name should not be a verb i.e.RegisterDevice, ProcessUser can not be a class name.

Methods should have verb or verb phrase names like postPayment, deleteDevice, or save.

Use pronounceable and searchable names

Do not use any abbreviated or short names, which is difficult to speak and discuss. Also, when any new developer join the team the variable need to be explained to them.

One should also take care not to give single-letter names and numeric constants to variables whose scope is bigger (i.e. class level), single-letter names can ONLY be used as local variables inside short methods.

These type of names are not easy to search and may create an issue while debugging or understanding the code.

string lousr; //logged out user
string fn; //first name of user
DateTime sdt;  //start date for query

As you can see in above examples, they are difficult to understand and also not easy to search, above all IDE will not show you the comments which exist beside those variables.

Why short name? why abbreviation? Most of the IDEs now a days provide facility to complete the variable name after typing first few characters, let’s use that facility.

Avoid encodings

Do not use any prefix or suffix to object, class or variable names. No need to add m_ for member variables, or adding string as suffix to the variable. IDEs are smart enough to provide us that information, we do not need to encode it in our names.

In the similar context, the consumer of the library do not need to know that they are dealing with abstraction and expose IUserService, If one must encode either the interface or the implementation, choose the implementation. Calling it UserServiceImp

Avoid Disinformation

Creating a confusion using names is very painful and it creates lot of confusion. For example, naming a string variable isDataExistor naming a grouping of users as a userList unless it’s actually a List.

Do not surprise end users by doing unexpected things in methods, such as modifying state in GET methods.

Do not create god classes

RequestHelper
BaseController
StringUtils

Creating above classes without clear responsibilities are bound to create GOD classes. Do not create a catch all class by providing very generic name and not defining its responsibilities.

Summary

Naming is hard and it requires skills to provide better names to variables, functions and classes, but it pays off. By providing better names we make our program readable and makes it easy for anyone to understand it.

Here are few general things to keep in mind

• Any fool can write code which computer can understand but it takes skills to write code which humans can understand
• Do not hesitate to change the name if the context has changed
• Read the code after you write it (clarity is the king)

Our goal, as authors, is to make our code as easy as possible to understand. We want our code to be a quick skim, not an intense study.