Choosing a name has a huge impact on the readability of the code.

In this post, I will walk you through some of the bad and good examples which might convince you why naming matters.

Project directories:

Can you guess which project serves as an admin website, mobile app, and server-side API’s?

Here, The developer not only failed to give attention to naming but also masked his original intent of each project with some other words. Confusing?

---

The sentence:

P and Q went to R. They had a good dinner at S followed by T and then they came back to U.

Could you read the above sentence, understand its clear intent and reconstruct it after hours even though it’s a small sentence?

For me, it’s difficult to understand due to the usage of abbreviations. It will lead me to make different assumptions.

---

Code snippet:

I am sure you have figured out what is this small code snippet doing. However, it was not that easy even though it was a small code snippet.

Now think about a project that contains more than 1000+ classes, modules, methods, files, and many more.

The complexity and frustration will be increased in the same magnitude if developers don’t give attention while naming those.

Don’t you think it will be painful for the maintenance developer as well as your future-self to visit and understand the intent behind the code?

---

Real-life analogy

Everything in this world has meaningful names. It helps our brain to understand, remember and figure out the things at ease. It means less mental mapping.

When you visit hypermarket, you could easily figure out groceries, fruits, cosmetics and so on.

You could easily fetch handwash, facewash, aftershave, sanitizer, liquid sanitizer, moisturizer, cold-drinks, cookies, water bottle and so on. Thanks to proper naming to the categories, items and so on.Naming matters!

---

Let’s revisit the above examples with careful naming.

Project directories:

Uglier way:

Better way:

---

The sentence:

Uglier way:

P and Q went to R. They had a good dinner at S followed by T and then they came back to U.

Better way:

Tom and Jerry went to a Mall. They had a good dinner at a restaurant followed by a movie and then they came back to their Home.

Do you realize the power of effective naming?

---

Code snippet:

Uglier way:

Better way:

Just looking at code snippet, it is crystal clear that code is working on height, length, and breadth to compute surface area and volume.

Now with proper naming to the variables, A small code snippet with careful variable naming makes developers life easy.

---

Imagine what will happen to readability, understandability, and maintainability if you show the same dedication while naming everything in the project.

We as a programmer try to solve the customer requirement or problem by creating various projects.

These projects may have directories, assemblies, namespaces, packages, files, classes, modules, properties, fields, events, method arguments, method parameters, UI elements, UI attributes, UI styles, validators, services, translation files, translation keys, command-line utilities and many more.

All of these things should have a meaningful name so that they convey their intent. You should be able to figure out what they are doing by just looking at their name.

Perhaps they should answer all the big questions that you or future maintenance developers would have.

Naming matters! Please give attention to naming everything in the programming!

---

Dattatray Kale | Being software craftsman
I am an application developer based in Pune, India. I am willing to wait for the right opportunity – Datta CV PRACTICES…blog.beingcraftsman.com

120308

What do you understand after reading the above number?

It is just raw data. The interpretation is left to the reader of the data.

However, the reader may not get the intent behind it.

• It could be a zip code of a city.
• It could be a birthday in DDMMYY  format.
• It could be a telephone number without the area code.
• It could represent N number of things.

Do you agree with me that using just raw data does not convey its intent?

Similarly, a magic number in code is like raw data which does not convey its intent to the reader of the code.

A magic number is a numeric value that is used in the code. This value has unexplained meaning and hampers readability of the code.

Here I did not understand the meaning of magic number 10000000.

Whether it is a size in Bits, Byte, KB, MB, GB?

Well, let’s introduce the named constant and see what happens.

As soon as you give metadata about the data i.e. relevant data it becomes information to the reader. The reader can work with it easily as the intent is clear.

Another example:

Bad way

Better way

Thus, named constants could be used to provide data about raw data so that reader of your code could easily figure out the intent.

Hence, Replace magic number with named constants.

Dattatray Kale: Crafting Software Excellence for Over a Decade

Conditionals play a vital role in code for performing business decisions. These conditionals should be easy to read.

If conditionals are complex then it might hamper readability. You would end up introducing more bugs if failed to understand its intent. Every time you visit this code, you will need to debug it to understand the intent.

Complex conditionals:

Look at above conditionals in if clause. It is clear that it is performing too many checks related to the package of the items. Please note that this package was ordered from an online e-commerce site and then performs important business decisions.

It will be difficult for the maintenance programmer to figure out each condition and know what question it tries to answer.

Let’s make the maintenance programmer’s life a little easy by writing readable code using encapsulate conditionals that have intuitive names and give the answer in yes/no format.

Better way:

Another complex conditional

Preferred way:

---

Dattatray Kale | Being software craftsman
I am an application developer based in Pune, India. I am willing to wait for the right opportunity – Datta CV PRACTICES…blog.beingcraftsman.com

The negative conditionals in code blocks are most of the time difficult to read and understand.

It becomes worse when you make the conditionals anti-negative.

Before

Try to read above code snippets and try to understand it. Please note the highlighted parts. Does that code reads like

• When inverse of a package is not damaged then report an error: “Package is damaged”.
• When inverse of a package is not empty then report another error:
  “Package is empty”

Ouch! Unreadable? Complex? Painful, isn’t it? Let’s revisit the same condition with positive conditionals.

After

---

Another example:

Before:

Above snippet is showing hours worked for the day if it’s not non-working day!

After

Now, this reads like simple statement. Show hours worked for working day.

---

Dattatray Kale: Crafting Software Excellence for Over a Decade

Extract method is the most frequently used refactoring technique. It reorganizes the code for better reuse and readability.

Ah! alright. Let’s proceed.

Use the extract method in following cases —

When your class contains a long method.

A long method does more than one thing and it is not considered as cohesive. The method more than 10 lines could be considered the as long method.

See this example of a long method, It is doing more than one thing.

Setting up GST rates, item/category mapping, accepting user inputs, calculation and so on. 

A long method is considered a code smell. 

Now see the refactored version of the above long method.

It is divided into small, cohesive, fine-grained methods which are doing one and only one thing.

---

When you favor a comment to express the intent of the code.

Before

 ...
// Parse input and convert it into Document
var xDocument = XDocument.Parse(input);
var document = new Document
{
   Title = xDocument.Root.Element("title").Value,
   Text = xDocument.Root.Element("text").Value
};
...

Here let’s get rid of comment [Parse input and convert it into Document]. 

After

...
var doc = ParseInput(input);
var serializedDoc = JsonConvert.SerializeObject(doc);
...
private Document ParseInput(string input)
{
    var xDocument = XDocument.Parse(input);
    var document = new Document
    {
        Title = xDocument.Root.Element("title").Value,
        Text = xDocument.Root.Element("text").Value
    };
    return document;
}

---

When the extract method helps you to improve readability.

Do you know that people extract method for a single line too? Because it adds to the readability of the code. Sometimes a statement may be difficult to interpret. In that case, you could use the extract method to convey intent instead of taking the aid of comment.

---

When there is a code duplication or copy-paste.

Consider below example, it is formatting date and code is duplicated. Perhaps, lines are copied and pasted.

Before

    var formattedStartDate = startDate.ToString("dd MMMM yyyy");
    var formattedEndDate   = endDate.ToString("dd MMMM yyyy");

As soon as you see copy and paste of lines of code then go for an extract method refactoring even if it is a small portion of code.

After

    var formattedStartDate = FormatDate(startDate);
    var formattedEndDate  = FormatDate(endDate);

public string FormatDate(DateTime date)
{
   return date.ToString("dd MMMM yyyy");
}

---

The advantage

• Code becomes more readable.
• Fine-grained methods make code easier to understand.
• You can easily plug-in and plug out the implementation for some routines.
• When your method becomes cohesive, you can easily spot the bugs in the code.
• Your calling method reads more like a sentence.

---

Points to Ponder —

• Remember, keep the method short, well-named, and cohesive to get more benefits out of it.
• Your calling method should read more like sentences.
• When extracting a method, a developer should think about the cohesiveness of the class. should ask a question to oneself: Does the extracted method really belong to this class? If Not, then move it to the appropriate class that should perform that operation.
• Small methods really work only when you have good names.
• Don’t just extract method if you can’t give the meaningful name.

---

---

Dattatray Kale: Crafting Software Excellence for Over a Decade