Basic Clean Code

Hi, it’s my first time on posting in Medium :)
I had never written any article about Tech before. I usually write a fiction. I love it, especially short story. I usually create the skeleton first what things I would like to write. It reflects the plot of the story. By doing that, I write more structured story in order to make the readers understand.

Being a Software Engineer makes me realize that do programming (coding) is also the art of writing. We should write code that other people (in this case, other Software Engineers/Developers) understand what we write.

This Illustration is from https://www.redbubble.com/people/krego/works/15977767-clean-code-uncle-bob

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
-Martin Fowler, Kent Beck, John Brant, William Opdyke, and Don Roberts (1999) Refactoring: Improving the Design of Existing Code. Addison-Wesley.

So, in here I tried to share to you about Basic Clean Code. Because mostly I use Golang, the sample is in Golang. I think the principle of basic clean code is quite the same for all programming language.
Disclaimer: this is based on some references and my experience.

Why We Need Clean Code?

1. Peoples come and go
In a company, employees come and go. We can still ask the related developer about their code when they are still working with us. But once they go, we should understand it by ourselves. Also, when new people is coming, they should learn the code. What if the code is messy?
2. Collaborate with others
It’s related to point number 1. We mostly do not change code only by ourselves, but we collaborate with other developers. Remember that we are working with the others. :)
3. Readability
Other developers should easily understand what the purpose of our code is. It doesn’t only mean for algorithm, but also naming for variable or function. The simple things that matter.
4. Modularity
A function we create should be modular in order to be re-usable by other function.

Things should be consider when writing clean code

1. The Sequence of Libraries (Packages) Import
First, we usually do not write only in 1 file. Second, we sometimes need a function(s) from other people’s repository or even our own repository’s package.
If we import many libraries/packages which are not in the right order, it will cause messy in our code. It’s better for us to define the sequence of libraries (packages) import.
For example, The sequence are:

- Golang library
- Controller package from our own repository
- Model package from our own repository
- Other package from our own repository, like util or common package
- Third party repository

It depends on your preferences, but usually it’s preferred to put the third party in the last one.
2. Meaningful Name

This Illustration is from http://devhumor.com/media/when-you-try-to-choose-a-meaningful-variable-name

2.1 Variable name
Use clear noun to make others understand what it is. For example:
- Single variable

- Variable on Looping
Usually, we easily find something like:

What is “i”? What is “j”?
Maybe at that time, we remembered what it is. But, months later, who knows?
We need to re-read the code in case we forget it. So, don’t do that.

Better we use a specific noun to depict what the variable really is.

For example:

- Struct name

People will be wondering. What is “data”?
What data do you mean? Can you imagine if there are more than 10 struct name is “data”?

So, it’s obvious. Based on the name, people will understand clearly.

2.2 Parameters name

Maybe, it’s quite OK, but let’s imagine when it has more than 1 parameters.

2.3 Function name

What is the purpose of the function? What does the function do? “Get”, isn’t it? “Set”, isn’t it?

Use clear verb for function name. So, the other developers will get easily what it does only by reading the name of a function.

2.4 Constant

Maybe that above function is still good if the function is still small and not much.

For static value, it’s better to use a constant.

3. Function
A function, in general, is a small piece of code that is dedicated to a perform particular task based on some input values.

- Small
A function should be small, has certain purpose. If it has many task to do, it’s better to refactor it.
- Reusable
Clean code contains no duplicate code. If a function already does a certain task, we can reuse it in another function.
- Total Parameters
If total parameters is more than 3 or 4, we should check it, if it does many task or if many algorithm merged in 1 function.
On SonarQube, we are recommended to use max 4 parameters.

This screenshot is from https://rules.sonarsource.com/typescript/RSPEC-107

4. Comments
The best kind of comments are the ones you don’t need. But is it bad to put comment in the code? No. It depends on needs.

Code Tells You How, Comments Tell You Why.

When to give comments?
- Legal comments

// Copyright 2014 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the “License”);
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0

- Informative comments

// Supported format: yyyy-mm-dd hh:mm:ss

- Complex Logic
Need comments to understand what that hard algorithm does.

// This will get x data, compare with in y data.
// Then, it will do…

When not to give comments?
- Nonsense comments

- Comment for obvious function
Redundant information. Don’t need to do this:

// This function is to insert user
func InsertUser(){}

Additional Things

Below based on what I have done during being a Software Engineer.
1. Commit

- Only 1 Commit in 1 Pull Request.
- If it has more than 1 commit, then squash it.
- Commit message also should be considered.

Messy one:
Fix bug

What bug? What do you fix?

Better one:
Improvement on x when y by using z

Give detail of what you are trying to change.

2. Unit Test
Last but not least, don’t forget to complete the unit test! It must pass all the test. It’s important to make sure function that we created run as we expected.

You can read more about unit test on:

https://medium.com/@erhemdiputra/how-to-write-unit-test-in-golang-8ebdbfb7cf80

Conslusion

Clean code is not only about algorithm, but also simple things that matter, such as variable name, function name, and total parameter. In the end, the code must clean to make other developers understand what we write. I know that creating clean code is not easy. It takes longer time.

It’s better to take extra effort today to save pain tomorrow, in this case refactor code of course.

Always remember that we collaborate with other developers. So, make sure the code that we pushed into Production is clean.

Read More

https://rules.sonarsource.com/typescript/RSPEC-107
http://slides.com/hamdiahmadi/deck-4bf133f4-2aeb-4cea-9435-3501cf0a971f#/5/2

Please leave any comments or suggestion. Thank you :)