Write Clean Code

Introduction

Why Must We Write Clean Code? To answer this question, let me tell you A story mentioned in the book "Clean Code" by the author

In the late 80s, a killer app was written. It was very popular, and lots of professionals bought and used it. But then the release cycles began to stretch. Bugs were not repaired from one release to the next.
Load times grew, and crashes increased. I remember the day I shut the product down in frustration and never used it again. The company went out of business a short time after that. Two decades later, I met one of the early employees of that company and asked him what had happened. The answer confirmed my fears. They had rushed the product to market and had made a huge mess in the code. As they added more and more features, the code got worse and worse until they simply could not manage it any longer. It was the bad code that brought the company down.

In short, writing code that is difficult to read and understand clearly makes it hard for other programmers to understand and modify the code.

So, if you want to write clean code to help your staff work without any question mark, like what this code does and what its meaning is, you can follow a series of Clean Code that comprises many chapters, and every chapter will contain some guidelines that help you to write clean code.
In this chapter, I will explain the Meaningful Names.

Agendia

1. What is Clean Code?
2. Guidelines to write meaningful names

What is Clean Code?

Clean code is code that is easy to read, understand, and maintain — not just by its original author, but by any developer who works on it later. It emphasizes clarity, simplicity, and discipline so that software remains reliable and adaptable over time

Meaningful 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, so how can we choose meaningful names?

Use Intention-Revealing Names

Names must reveal their intention
For Example

int d ; //  elapsed time in days

What do you understand when reading d? Nothing, so what happened if we write the next code?

 int elapsedTimeInDays;

The name d reveals nothing. It does not evoke a sense of elapsed time, nor of days. We should choose a name that specifies what is being measured and the unit of that measurement.

Let's see another bad Code, then improve it

public boolean isEligible(int age, int status) {
    return age > 18 && status == 1;
}

Why is this hard to understand?

This looks fine — short, clear, no complex logic. But it hides meaning:
What does Status represent?

• Is 1 active, verified, approved?

Why age > 18?

• Is this a legal requirement, a business rule, or just arbitrary?

What does “eligible” mean?

• Eligible for voting, registration, or something else?

The reader must stop and guess the context. That’s the same “implicitly” problem as before.

let's look Good Version

public boolean isEligibleForMembership(User user) {
    return user.Age > MINIMUM_AGE && user.IsActive;
}

private static final int MINIMUM_AGE = 18;

Improvements

• User replaces raw parameters → explicit domain object.

• MINIMUM_AGE constant replaces 18 → no magic number.

• Method name isEligibleForMembership → tells us eligible for what.

Now, the code reads like a sentence: “A user is eligible for membership if they are older than 18 and active.”

Avoid Disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning. For example, hp, aix, and sco would be poor variable names because they are the names of Unix platforms or variants. Even if you are coding a hypotenuse and hp looks like a good abbreviation, it could be disinformative.
Do not refer to a grouping of accounts as an accountList unless it’s actually a List. The word list means something specific to programmers. If the container holding the accounts is not actually a List, it may lead to false conclusions. So accountGroup or bunchOfAccounts or just plain accounts would be better.

Make Meaningful Distinctions

Developers create unnecessary problems when they name things only to satisfy the compiler.
Because names in the same scope must be unique, some programmers change names randomly or misspell them—causing issues later when “fixing” the spelling breaks the build.
Adding numbers or meaningless words may compile, but it doesn’t improve clarity.
If names must differ, their meanings should differ too.

Number-series naming (a1, a2, .. aN) is the opposite of intentional naming. Such names are not disinformative—they are noninformative; they provide no clue to the author’s intention. Consider:

public static void copyChars(char a1[], char a2[]) {
    for (int i = 0; i < a1.length; i++) {
      a2[i] = a1[i]; 
    }
  }

Improvment
Try to understand what the previous Code is doing, then continue reading.

code tries to copy a1 to a2, but using a1 and a2 makes you stop and think what are mean, so replace a1 with Source and a2 with destination

public static void copyChars(char source[], char destination[]) {
    for (int index = 0; index < source.length; index++) {
      destination[index] = source[index]; 
    }
  }

Now try to read the Code before and after, then think which is easier to understand?

Using Pronounceable Names

A large part of our brain is built for understanding spoken language, so our code should use names we can actually pronounce. Unpronounceable names make communication awkward — and since programming is collaborative, that becomes a real problem.

I once worked with a variable named genymdhms. No one could say it, so developers invented strange nicknames just to talk about it. It became a joke, but it still confused. New team members had to learn these meaningless sounds instead of clear, descriptive terms.

Using pronounceable names keeps conversations smooth and makes the codebase easier for everyone to understand.

For clarification, compare

 class DtaRcrd102 {
 private Date genymdhms; 
private Date modymdhms;
 private final String pszqint = "102";
 /* ... */
 };

To

 class Customer {
 private Date generationTimestamp; 
private Date modificationTimestamp;
 private final String recordId = "102";
 /* ... */
 };

Using Searchable Names

Don't use a Magic number. Replace it with Constant. Why are you doing that? Firstly, because the magic number is obscure, it does not have any meaningful. Secondly, if you want to change this magic number will find it difficult. Imagine you search for 7 number how many 7 in a project, and which one will change it.

Compare

int s = 0;
for (int j = 0; j < 34; j++)
{
    s += (5 * 4) / 5;
}

To

 const int WORK_DAYS_PER_WEEK = 5;
 int sum = 0;
 for (int j=0; j < NUMBER_OF_TASKS; j++) {
 int realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
 int realTaskWeeks = (realTaskDays / WORK_DAYS_PER_WEEK);
 sum += realTaskWeeks;
 }

Note that sum, above is not a particularly useful name, but at least it is searchable. The intentionally named code makes for a longer function, but consider how much easier it will be to find WORK_DAYS_PER_WEEK than to find all the places where 5 was used and filter the list down to just the instances with the intended meaning.

Class Names

Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.

Method Name

Methods should have verb or verb phrase names like postPayment and deletePage.

When constructors are overloaded, use static factory methods with names that describe the arguments.But why use the Static Factory method? Multiple constructors with different argument lists can be confusing. For example,

new Complex(23.0);   // What does this mean? Real number? Magnitude?
new Complex(23.0, 5.0); // Okay, maybe real + imaginary?

But when using the static factory method, it gives descriptive names to clarify intent

 Complex fulcrumPoint = Complex.FromRealNumber(23.0);
Complex vector = Complex.FromCartesian(23.0, 5.0);
Complex polar = Complex.FromPolar(10.0, Math.PI/2);

Pick One Word per Concept

Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes. How do you remember which method name goes with which class?

user.fetchProfile();
account.retrieveProfile();
customer.getProfile();

Here, three classes expose the same concept with three different verbs. That forces developers to memorise arbitrary differences.

user.getProfile();
account.getProfile();
customer.getProfile();

Now, the concept of “getting” is unified.

Don't Pun

Avoid using the same word for two purposes. Using the same term for two different ideas is essentially a pun.

Why?
It creates ambiguity. Developers expect consistency, so reusing a word in a different semantic context misleads them.

cart.add(item);       // puts item into collection
calculator.add(x, y); // performs arithmetic addition

Both use add, but the semantics differ—one is about collections, the other about math

cart.insert(item);       // clearer for collections
calculator.add(x, y);    // arithmetic addition

Now each word maps to a distinct concept.

Conclusion

Meaningful names are one of the simplest yet most impactful ways to improve the quality of your code. Clear, descriptive, and pronounceable names communicate intention, reduce misunderstandings, and make collaboration smoother. When functions and variables accurately reflect what they do, the entire codebase becomes easier to read, maintain, and extend. Good naming isn’t just a stylistic preference — it’s a core principle of clean, professional software development.

I’d Love Your Feedback

What naming habits have helped you write cleaner code?
Have you encountered confusing or funny variable names in past projects?

Share your experiences, thoughts, or even disagreements in the comments.
Your feedback helps improve the next parts of this series — and it might help another developer reading along.

Reference

Clean Code: A Handbook of Agile Software Craftsmanship