Hire a Maid to Clean Your Code
This article is part of Proyek Perangkat Lunak (PPL) or Software Engineering Project Course. Any information written here may or may not be true. Please use it wisely and let me know if there is any wrong information in it.
What is Clean Code?
The most popular definition of clean code is code that is easy to understand and easy to change. On the face of it this may get heads nodding and chins stroked, but ultimately it’s one of those definitions that states something without really stating anything at all. In the Agile methodology, clean code is an important part because it can maximize the collaboration process with other programmers. Therefore, Clean Code is very important and really helps the adaptive software development process, whose needs are always changing and evolving.
Why Clean Code?
- Code Maintainability: Writing Clean Code is writing good literature. It reflects you. Every line is stanza carefully handcrafted interwoven into a beautiful mosaic of code pieces.
- Code Readability: Writing Clean Code is explaining the Physics. The code should implicitly explain in small details exhibiting simplicity what the magical functions does.
- Code Smell Repellent : Writing Clean Code is like wine-making. It may take ceremonies but in the end you will feel comfortable with the code (at the least). Bugs will find it hard to hide.
- Code Epithet: Once you commit with version control. The name gets etched with the code forever.
Writing clean code is important because it allows you to clearly communicate with the next person who works with what you’ve written. Being able to return to previously written code and understand what it does is key, especially in the software development world. The more declarative code is the better it communicates, and the easier it is to fix problems when they arise. By writing clean code, you will make yourself a better teammate, employee, and developer.
How to Clean Code?
DRY
This is a very common software development principle. It stands for Don’t Repeat Yourself. And it essentially means that when you’re writing code, you should consider modularizing functionality that you use more than once. The simple solution is copy, paste, and modify. With DRY principle we just create one function in one place and then call/use the function repeatedly.
The opposite of the DRY principle is WET (Write Everything Twice). With WET, the same code is written over and over again. Here’s the example between DRY and WET principle
WET
// Flow A
user := getCurrentUser();
firstName := user.getFirstName();
lastName := user.getLastName();
fmt.Println(firstName, lastName);
// Flow B
user := getCurrentUser();
firstName := user.getFirstName();
lastName := user.getLastName();
fmt.Println(firstName, lastName);DRY
func getFullName(user User) {
firstName := user.getFirstName();
lastName := user.getLastName();
return firstName+lastName;
}
// Flow A
fmt.Println(getFullName(getCurrentUser());
// Flow B
fmt.Println(getFullName(getCurrentUser());
// Other Flows...
fmt.Println(getFullName(getCurrentUser());KISS
It stands for Keep It Simple, Stupid. Sometimes, when solving a problem, you might incur in what is known as over-engineering or how I like to call it: using a bazooka to kill a mosquito. It’ll get the job done, but you can definitely do the same thing a lot simpler.
There are moments when complexity is required, don’t get me wrong. When simple code, or a simple architecture is definitely not useful, adding complexity to your logic is required. However, more often than not, you should ask yourself whether you’re KISS’ing it or not.
SOLID
SOLID consists of five principles:
- SRP, Single Responsibility Principle
- OCP, Open Closed Principle
- LSP, Liskov Substitution Principle
- ISP, Interface Segregation Principle
- DIP, Dependency Inversion/Injention Principle
SOLID seems to need a separate post considering the items are quite large and complex. In essence, with SOLID, we can make programs more flexible, maintainable, extensible, scalable, etc.
Use Meaningful Names
Names are the smallest building block of code. Names are everywhere: Function, class, file, component, and container all have names. The best name for the names are the one that tells you what it does.
Comments
Comments are there to explain things your code does. Comments should be as little as possible. The code should be self-explanatory by its naming or its names.
YAGNI
Otherwise known as “You ain’t gonna need it” is a principle taken from eXtreme Programming that argues that you should not build functionality in advance, or rather, until you actually need it.
The point being that within an agile development framework, you should only focus on your current work iteration and not in the ones to come. This is because even though it might sound tempting to work ahead of time and deliver more functionality that you were expecting, the changing nature of the agile workflow makes the future unstable.
What do I mean by unstable? I mean that given the short-iterations that characterize this methodology, you can receive early feedback, potentially completely changing the future of your project and rendering that feature you delivered without needing, useless.
And many more…
Yes, if you want to know about all of the clean code principles you’ll be overwhelmed by all of them. That’s why in our PPL project we hired a few maids or assistants to help maintain our code clean.
Our PPL Assistants
GO Extension
Our backend program using Golang as the main language, the GO extension has helped us a lot on our PPL Project. It includes such features like:
- Linter
- Formatter
- IntelliSense
- AutoCompletion
- etc
The most useful feature related to clean code (in my opinion) is Linter and Formatter. The Golang Linter is pretty strict it will complain to you if there is any unused import. Also if there is any redeclared variable the linter also warns you to keep the code clean. And it’s also important to have formatter because we need to have same code style across developers who work on our project to maintain readability and maintainability.
Husky
Git hooks allow custom scripts to be ran on your repository. Husky is a very popular (30 million downloads a month) npm package that allows custom scripts to be ran against your repository. Husky works with any project that uses a package.json file. It also works out of the box with SourceTree! Husky helps us do more things along with git commands. For example, we can run npm test in pre-commit phase and do something else in post-commit phase.
We use husky in our FE repository because our FE is using Next.js that is part of npm package. This is our husky and eslint configuration.
With husky we can check some aspects of clean code before committing the code to git. From the code above, we check if our code already use the formatting convention or not, in line 6 we run the formatter with the style that we defined on .eslintrc. In eslint we state that code must sufficient certain style or clean code, such as, for unused import, it will trigger an error and if there is an unused variable it will trigger a warning, etc. After that husky will check the type convention in typescript, and the last thing husky will try to build the next app for our production.
SonarQube
SonarQube® is an automatic code review tool to detect bugs, vulnerabilities, and code smells in your code. It can integrate with your existing workflow to enable continuous code inspection across your project branches and pull requests.
— docs.sonarqube.org
If we accidentally push our dirty code to repository, then SonarQube will come to rescue. SonarQube will automatically SonarQube evaluate the quality of our code, including bugs, code smells, coverage, security vulnerabilities, etc. This alert indirectly pushes our team members to follow the clean code standards.
Final Word
Clean code is very important, especially in the maintainability aspect. But it’s almost impossible to know, remember, and implement all clean code principles. All you can do is just try your best, and let your clean code assistances help you with the things you forgot.
Thanks for reading and don’t forget to be grateful!
