Meaningful Names (Clean Code) — Why it is important for software developers?
Md Imtiyaz Ahmed
Posted on February 13, 2021
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](https://www.pluralsight.com/courses/writing-clean-code-humans)
[Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin)](https://www.amazon.in/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
Follow me [Twitter](https://twitter.com/imimtiyaz9) [Linkedin](https://www.linkedin.com/in/md-imtiyaz-ahmed-092a6597/)
Posted on February 13, 2021
Join Our Newsletter. No Spam, Only the good stuff.
Sign up to receive the latest update from our blog.
Related
February 13, 2021