DEV Community

Md Imtiyaz Ahmed
Md Imtiyaz Ahmed

Posted on • Updated on

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"

Alt Text

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

Clean

sendMail()
getValidUser()
exportZipFile()
Enter fullscreen mode Exit fullscreen mode

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);
   }
}
Enter fullscreen mode Exit fullscreen mode

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);
  }
}
Enter fullscreen mode Exit fullscreen mode

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)
    }
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Conditions:
Write implicit code around boolean variables

Not Clean

If(isValidationDone == true)
Enter fullscreen mode Exit fullscreen mode

Clean

if( isValidationDone)
Enter fullscreen mode Exit fullscreen mode

Not Clean

Boolean isEligibleforDiscount;
If(purchaseAmount >3000){
   isEligibleforDiscount = true;
}else{
   isEligibleforDiscount = false
}
Enter fullscreen mode Exit fullscreen mode

Clean

Boolean isEligibleforDiscount = purchaseAmount >3000;
Enter fullscreen mode Exit fullscreen mode

Use positive conditions

Not Clean

If(!isUserNotValid)
Enter fullscreen mode Exit fullscreen mode

Clean

If(isValidUser)
Enter fullscreen mode Exit fullscreen mode

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

Not Clean

If(process.status == “completed”)
Enter fullscreen mode Exit fullscreen mode

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){
}
Enter fullscreen mode Exit fullscreen mode

replace constant or enums with magic number

Clean

Int promotionEligibleYears = 10;
If(employee.yearsWorked > promotionEligibleYears)
Enter fullscreen mode Exit fullscreen mode

“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

Top comments (5)

Collapse
 
alissonzampietro profile image
Alisson Zampietro

Great post mate! I've one suggestion, I usually use the "get" as method name when it represents the class name data, it makes the method calling more elegant, for example:

User.get()

instead

User.getUser()

Collapse
 
imtiyazcode profile image
Md Imtiyaz Ahmed

Thanks Alisson fo reading..
There is no problem when you use get() method with Class or object. it will reflect the intent that activeUser.get() means method is calling for an active user. But you can't be sure that get() method will be used always like that, for example, it can be used like this.get() or simply get(). Since you have created the method you may always use with some object or Class, but how will other developers know that and they make a mistake of unclean code while using such existing methods.

Collapse
 
arvindpdmn profile image
Arvind Padmanabhan

Thanks. Inspired me to write a Devopedia article on Clean Code. BTW, the last quote is from Donald Knuth.

Collapse
 
imtiyazcode profile image
Md Imtiyaz Ahmed

Thanks Arvind for pointing out the typo. Will update that.

Collapse
 
jadenconcord profile image
Jaden Concord

Thank you for the post. The Javascript version for "Clean Code" is here which I have been going through recently