Writer: Rahmat Kurniawan
Editor: Monic Andyani
What a software engineer does in a nutshell is that we create applications and/or products with a lot of features within. When our products are used by many clients, most of the time they would request several changes that are tailored to what they need. The changes could be in the form of a customization of the features that are already present or even a request to add new features. This can prove to be a challenge, especially when we have more than two clients, requesting different customization.
Our product consists of several applications, therefore every customization means another effort to move or tweak certain applications or features which we call context switching. In this case, every engineer is required to understand the code of all applications and/or projects. It seems impossible at first, however, the solution for it is one coding fundamental that's often overlooked, which is writing a clean code.
Take a look at the following code, is this code clear enough for you to understand?
There are several questions that might pop-up in your head as you read them. What does the pay function is purchasing? Whiskey Tango Foxtrot does const u and i mean? These questions require several scroll-up so we can understand the meaning — which is time-consuming. This will be frustrating if you are on the receiving end of the context switching. This means that by merely finishing your task faster is not worth the technical debt that will bother us in the future.
Luckily, AccelByte has implemented the habit of writing clean code from the start. This is one of the core cultural tenants for the engineering teams since implementing a clean-code approach will significantly improve our productivity as an engineer.
So, can I see an example of a Clean Code?
From the nightmarish example above, I have rewritten them into a better, cleaner, and much easier to understand code.
Now with this code, it is known that this function will work for paying in-game items, in which the function requires two parameters namely userId and itemId. For the function itself, we now understand that there is an instruction to make an order and to pay for the order. Now, this code is efficient, much more understandable and sparks joy.
Well, it ain’t stupid if it works… right?
We all know the fundamentals of a clean code — it should be easy to understand plus easy to modify or change. But why should you care? Well, your code is the prime representation of your programming skill and your train of thought — keep this in mind because your code will be read by other engineers in your team. Here are reasons why you should write a clean code:
- You will be free from unnecessary confusion in the future. You wouldn’t need to guess what that line means or read your code all the way through only to understand what it means
- It will be easier for the team to assist you in finishing your tasks. What if you’re on a leave but we forgot a thing or two? Surely, your team would love to help you out to make sure it is finished on time — but we all know they wouldn’t love reading a messy code!
- What if you encountered a bug? The answer is obvious — debug them! Clean code with a well explanatory error message will save your time in debugging, now isn’t that what we all want?
- Precaution is better than cure. By investing your effort in writing a clean code, we are taking the preventative approach in avoiding technical debt in the future.
Great, so where do we begin?
There are two mantras that you need to internalize so that you will soon be able to write clean code with ease. They are the DRY mantra and KISS mantra — let me break them down on the following section:
DRY is an acronym for “Don’t Repeat Yourself”. When you write your code, sometimes we would like to create the same or similar code twice or more in a separate file. You would copy and then paste the code — it will be more difficult to refactor if there are changes in the future. Instead of making the same code repeatedly, it would be so much better if we make our code more modular.
KISS is an acronym for the design principle “Keep It Simple, Stupid!”. The computer can only understand binary, it’s either 0 or 1. Therefore humans created a programming language so we can give proper instructions in a way that we could understand, and is readable by the computer. Therefore, we should write our code in a simple and straight manner that is easily understandable by human beings.
We also need to keep our methods small, each method should never be more than 50 lines! One way to do this is by assigning one method to only solve one small problem instead of many use cases. When you realize you have a lot of conditions in the method, break them into smaller methods. This will make your code easier to read and maintain and also you can find bugs a lot faster.
BONUS: Extra tips for extra clean code!
- Review your code yourself
Keep in mind that perhaps one day you need to make some changes in the code that you are currently working on. Will it be easy to change it by then? Will you understand the meaning of the code immediately? Or perhaps you still need to see the previous code that uses that code? If you feel the need to see the previous code when reading the code you are currently working on — it means that it isn’t clean enough.
- Review your code with your colleagues
Opinion from your colleagues is very important for it helps you to improve your code and they can notify you when something is missing or seems to be out of place.
- Proper naming conventions
Every language has its own naming conventions, or perhaps your company has its own naming conventions. Make sure that you are using the appropriate naming conventions to avoid problems in the future.
- Keep an eye on your formatting
Formatting (such as block indentations, statements, column limit, comments, and many others) is very important for a clean code, it’s made easier to read:
Use Braces for all control structures (such as: if, else, for, etc). The first statement of a non-empty block must begin on its own line. Use the following link as a reference.
There’s a braces condition that can be ignored
- Ternaries operation (source)
- ‘If’ statement without ‘else’ statement
B. Column limit
A line of code should be less than 80–120 characters to make it easier to read, but there are some conditions that can’t follow this rule like long URL and specific commands.
- For multi line comments, you should use /** … */ (source)
- You can use // for single line comment, make sure you put it above the subject of the comment. (source)
- Add an empty line before the comment unless it’s on the first line of the block (source)
- Start all comments with space.
D. Block Indentation
Ask yourself… does this code spark joy?
Breathe in, breathe out. Congratulations! Now we have reached the end of the page, keep in mind that writing a clean code will not only benefit yourself but also your team as a whole. A code is a representation of your skill and your train of thoughts — start writing cleaner from now, eventually, it will be a habit that will increase your productivity in the future.