Naming Conventions

Introduction

This is a new series of articles which dictates the best industry practices being used today while coding. The language of reference would be Java but I am sure the concepts will work across languages. There might be few in the list which you need not worry in case you are programming in more advanced languages.

The idea is to discuss one best practice a day and give supporting examples and references. I trust that it can help each and every one of us.

Before we embark on this long journey, I would like everyone of us to understand what exactly a “best practice” is and how do we know that what is a best practice?

To answer that, I would just say that its a result of evolution of several years of programming and trial and errors. One of the famous quotes is as follows:

“Practice does not make perfect. Only perfect practice makes perfect.”

I am sure you will get all this information in one or several books, I am just trying to put it up on-line and create a repository so that anyone and everyone who may or may not have access to a relevant book will get to read it anywhere and everywhere.

Why am I writing about a basic stuff like naming conventions?

I do not agree with Shakespeare, I believe name is the one of the important things in real world as well as the programming world. In my 7 years of programming I have come across certain maintainability issues that I am forced to write about the naming conventions best practices.

What is a good Naming Convention?

A good name should ideally define its purpose.
For e.g. you cannot name your pet dog as Router, it doesn’t make sense to others. Imagine you telling your friend that “I took my router for a walk in the park”.

There are three major things regarding the naming that we should worry about while programming.

Naming Conventions for Fields/Properties

Fields are mostly attribute and they store property values (which are basically Noun). For e.g.:

  • A variable to store rate of interest would mostly be declared as float interestRate = 0.0f;
  • A variable to store details of an employee shall be declared as Employee employeeDetails = null;

and so on… looks very simple Yeah!

Naming Conventions for Classes/Interfaces

Classes : A class represents an real world object (basically a Noun). A class to represent the real world entity like Driving License may be declared as class DrivingLicense{}

Classes have few more challenges mostly in case of layered architecture. Sometimes we need similar objects in various layers of our application, to name them the layers:

Domain layer where the class can be named as DrivingLicenseEntity ,
Web layer where it can be named as DrivingLicenseDTO
and the Business Layer where we can call it DrivingLicense

Another naming challenge is while defining APIs
Interfaces : (Lets say we want to name an interface which provides API for reading data from any source)
There are two conventions which people follow:

  • Start with an I for the name ‘IReader’
  • Without the I just ‘Reader’

Second one seems to be much better than the first one due to certain reasons.

  • I have my reasons for saying that, we are trying to provide an API here, and if it is a successful API many fellow programmers will end up using it. Hence, the names should be as small and readable as possible.
  • Also, consider a scenario where we used the first naming convention, definitely the implementing class will have a simpler and better name, but our purpose is to promote the use of interface and not the concrete class. So, we must name the interfaces better.
  • Another reason might be that an interface can have many implementations and the names of the implementation may vary as per the specific implementation. I strongly recommend not use Impl as a suffix for the implemented classes, because in a project which is big enough, it is less likely to have just one implementation of the interface. In our case a BufferredReader implements a Reader, a StreamReader implements a Reader etc.
  • Also, in modern IDEs searching for a interface with name would become tough as there will be so many of them starting with I. So better choose effective names.
  • I can think of couple of more reasons, like imagine we have a definition of class hierarchies where many of my classes are extending an abstract class.
    For e.g.: class BufferedReader extends Reader{}. where Reader is an abstract class. Now I want to change to an interface approach and I want to follow the convention with I. Then I might end up changing this in all the implementing class. Not really a good task. Although, the IDEs will do so and also we should not do such changes once the API is public as backward compatibility is more important than anything else.
Naming Conventions for Methods

Methods are mostly considered as verbs (an action to be performed). For e.g. if we need to define a functionality like reading from a file and storing it in another file. It might not be a good idea to combine both of these functionalities in one method. We must write two methods like String readFile(File file){} and int writeToFile(byte[] content, File file){}

At the end here are few more tips about Naming Conventions:

    1. Avoid very very long names. Names up to 25 characters are still readable, anything above this becomes a little difficult for readability.
    2. Maintain Uniformity, It is well known fact that a project is done with several members in the teams, if all of them do not have a common agreement for naming conventions, then the code will look dirty and people will run into confusion.
    3. Camel casing is your good friend, it increases readability and it is easily understood in the developer community.

Stay connected and stay Subscribed