Meaningful Names (Clean Code) — Why it is important for software developers?

Robert Martin (Uncle Bob) once said,

"Any fool can write code that computers understand. Good programmers write code that humans can understand"

Many of us take pride in ourselves when we provide a solution and write code for a complex problem, but what makes you a complete developer when you write code which your fellow developers can easily understand and giving meaningful names to the variables, functions and classes plays a vital role in that.

Let me tell you why?

I did understand this principle of clean code after a few years into professional coding when I struggled to understand my own code written just a few months ago. You must have us gone through a situation where you would like to prefer writing a fresh code for a bug fix or changes in the requirements instead of incorporate changes to existing code of other developers. These codes are technical debts to the team and organization and if you are also one of them who does not put deliberate effort to keep your code clean and followed the principles of clean codes, someone else down the line reading your code will feel the technical debt you have written that will increase the burden for maintainability, scalability and code debugging.

Providing meaningful names is one of the many principles of clean code and I feel providing meaningful names is the most important one.

Here are the rules for providing meaningful names

Naming Classes:
One class should carry only one responsibility. Hence this intent should reflect through the class name. A good rule of thumb while naming classes and methods is to think of nouns while naming class and verbs while naming methods.

Not Clean

Builder 
Processor 
WebsiteBO 
Utility

Above class names do not tell what specific single responsibility it holds and hence becomes magnet class for other developers as they shove other responsibilities to these classes.

Clean

User 
QueryBuilder 
ProductRepository

Naming Method:
By method name reader should understand what is there inside the method and should have only one job to do.
Not Clean

send()
get()
export()

Clean

sendMail()
getValidUser()
exportZipFile()

Not Clean

//Code 1
Public Boolean sendSuccessMail( User user){
  If(user.status == STATUS.active && 
          isValidUserMail(user.mail)){                   
      //code for generating emailId,subject and email body
     MailUtils.sendMail(mailId,subject,body);
   }
}

code 1 breaks 2 rules of clean code. It not only performs two responsibilities and but also its name does not indicate its jobs clearly. Which may cause lots of problem in future.

Let's look at the better version but still not clean

Code 2
Public Boolean checkValidUserAndSendSuccessMail( User user){
If(user.status == STATUS.active && isValidUserMail(user.mail)){
   //code for generating emailId,subject and email body
   ....
   MailUtils.sendMail(mailId,subject,body);
  }
}

Code 2 with method name checkUserAndSendSuccessMail is somewhat better in terms of clear intent, but it still carries more than one responsibility which is not good for code reusability and codebase may end up with many duplicate codes and in many places, you may need different logic for user validation or only mail send. And if there is any change in user validation code, it will not only impact user validation test cases but also send mail test cases.

Clean Code

Public Boolean checkValidUser ( User user){
  return user.status == STATUS.active && 
                   isValidUserMail(user.mail)
}
Public Boolean sendSuccessMail( User user){
  //code for generating emailId,subject and email body
  ...
  MailUtils.sendMail(mailId,subject,body);
}

Boolean isValidUser = checkValidUser(user);
   If(isValidUser){
      sendSuccessMail(user)
    }

Warning signs for methods carrying multiple jobs: AND, OR, IF etc
Avoid Abrr like isUsrRegis, regisDone

Naming Boolean variable:
Boolean variable should always ask questions and should be symmetrical when used in pair.

Not Clean

send
complete
close
login
open/completed

if you declare these kinds of variable, the reader will face problem to understand the use of these variables later in code something like if(login == true)

Clean

loggedIn
isMailSent
isValidationDone
closed
open/close (symmetric)

Conditions:
Write implicit code around boolean variables

Not Clean

If(isValidationDone == true)

Clean

if( isValidationDone)

Not Clean

Boolean isEligibleforDiscount;
If(purchaseAmount >3000){
   isEligibleforDiscount = true;
}else{
   isEligibleforDiscount = false
}

Clean

Boolean isEligibleforDiscount = purchaseAmount >3000;

Use positive conditions

Not Clean

If(!isUserNotValid)

Clean

If(isValidUser)

User ternary operator
Avoid using “stringly-typed”/”hard-coded” value

Not Clean

If(process.status == “completed”)

Instead of stringly typed value, we can use Enums and keep all the status of the process in a single place and we can get rid of typos with strongly typed and help maintain code base with a single place to change.

Avoid using magic numbers
Not Clean

If( employee.yearsWorked > 10){
}

replace constant or enums with magic number

Clean

Int promotionEligibleYears = 10;
If(employee.yearsWorked > promotionEligibleYears)

“Programming is the art of telling another human what one wants a computer to do” — Donal Knuth

For more knowledge on the clean code principles, you can go through below listed resources

References & Resources:
Clean Code: Writing Code for Humans
Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin)

Follow me Twitter Linkedin