Reducing “huh??” Moment From Your Code With Clean Code

bad_code.png (740×277) (xkcd.com)

Imagine you were having fun with your code, creating an app for a company that you always dreamed of. After you had made notable progresses, you had to stop for a while because of changes in requirements. After a few weeks of leaving your app unattended, you finally went back into your app. This time, you were aided by another colleagues as a team. First things of, you had to review your code with others and.. this is where your disaster began. You had just realized upon reviewing it, that you made a mess of a code, creating a near non-readable code. Yes, it works and maybe haven’t got any bug yet, but this code is so impossible to understand that it took hours for your team to understand it. Any attempt to extend the functionality of your code will always be haunted by bugs that can appear anywhere because of your low understanding of this code. Because of it, your app finished way past the deadline.

Above illustration is just an example of how a bad code can ruin your whole team. The importance of it, considering programmer mostly work in a group, is high enough for you to consider. So let’s deep dive into clean code and understand it better.

What is Clean Code?

Many experienced programmers has their own definition of clean code, here some of them:

Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control. - Robert Brooch

Brooch saw clean code as an indicator when your code achieved desired functionality as simple as possible with easy to understand flow.

I could list all of the qualities that I notice in clean code, but there is one overarching quality that leads to all of them. Clean code always looks like it was written by someone who cares. There is nothing obvious that you can do to make it better. -Michael Feathers

Feathers defined clean code as a code that was written well enough that there are no way to make it better.

While there are many definitions of clean code, I usually go with this generalized definition of clean code:

Clean code is code that is easy to understand and easy to change.

Code that is easy to understand and change is a sign that you do not make a mess of code and keep your code neat enough.

Clean Code Advantages

Why should we care about clean code? Can’t we just create a code that is functional? That’s all matters for our user anyway, isn’t it? Well, there are many arguments out there that explained why clean code is important. Thus, I will try to conclude it into my own argument:

1. Most of the time, code is not something that you wrote one time only. At the very least, you had to do maintenance of your code after some period of time. You ought to visit it at sometime later either for maintenance or developing your code further by extending your current code. Clean code will reduce time in understanding your code and make your work way more efficient.
2. Programmers tend to do works collaboratively. We tend to divide our application into smaller chunks, and create it one by one, just like building blocks. Sometimes, your block of chunk depends on or use another chunk in its program. You had to read that chunk code which was written by another programmer. Clean code will help you understand each other’s code and reducing any misunderstanding that can be happened.
3. Elegance. There’s nothing that proud us, programmers better than writing a straightforward code without any unused/unreadable code, isn’t it?

After reading arguments above, have you agreed that clean code is important? If so, let’s familiarize ourselves with clean code principles!

Clean Code Principles

Clean code had some important principles that we must adhered to:

1. KISS (Keep it simple stu*id!): Unnecessary code should be avoided when you create a program. Create your code as simple as possible, so you can understand it clearly without any roundabout method that can make another mind’s blown. The question to ask when you’re writing code is “can this be written in a simpler way?”
2. YAGNI (You ain’t gonna need it): Well, an easy way to explain this is, just create a functionality that you were asked to do! No need to create something that isn’t needed and wasting your time.
3. DRY (Dont repeat yourself): Duplications is a waste of line and time to understand it. It also a sign that you can generalize it into a function which suits its names better. Code with many duplications is not a simple one and took time to understand it!
4. High cohesion, loose coupling: Clean code embraces you to make function or class that has loose coupling (low attachment between each others) and high cohesion (keeping a code that related to each other in one places). This, will make any changes in your code less deadly.
5. Composition over inheritance: Composition being favored in clean code because of its flexibility. Inheritance forces us to create a skeleton of our object ahead, making them prone to any changes.
6. Consistency: There’s nothing better than stick to what you had agreed. It makes your code clearer and less confusing.
7. Favor Readability: There’s no point of clean code if humans can understand it. Thus, you had to make your code readable, even at the expense of conciseness.

By agreeing to those principles, we are ready to implement clean code in our program. So at last, it is time to implement it in our program!

Example Of Clean Code Best Practices

There are many best practices in clean code. To keep it short, I will give an explanation and example in my project about clean code rules for names, function, and comments.

Names

When you create a function or variables, you had to create a name with clear meaning about what its contains. By creating those meaningful names, it will conveys what your code to other people, thus lessen your time of explaining and creating a comment of it. An example of this is shown below:

An example of meaningful names

As you can see, I create a list with not_filled_field as its name, thus conveying that the list will contain fill that will not be filled and skipped it in our validation. I also make a variable kuliah_serializer, meaning that it is a serializer which will convert our received data into python objects and being related to kuliah.

Function

According to clean code, function should have this criteria:

1. Small: Function should be small. This will make sure that it works for one specific task, thus making it easier to understand by reading its name. There are no general agreement of maximum line of code in function, however my lecturer in advanced programming class, Mr. Hafiyyan Sayyid Fadhlillah, S.Kom., M.Kom., said that our function should not exceed 15 lines.
2. Do one thing: A function should only do one specific thing. By doing this, we can avoid any duplications of code and make it more generalized while understand what our function do better.
3. Descriptive names: Just like what I have explained above, descriptive names make it easier to understand your function’s behavior just by reading its name.

An example of good function in clean code is shown below:

Example of good functions

As you can see, our function there ticked all of criteria a good function has. It is small, only consist of 4 lines, created for one specific purposes, that is validating jenis_kegiatan field, and has descriptive names that you can understand even when you do not understand its code. It also raise an exceptions for any unintended behavior, instead of using if-else, one of clean code criteria.

Comments

I have a general tips for this, which is:

Try not to comment at all!

In most cases when you feel that you need a comment, you can omit it just by having clear names in your functions, variables, or objects. I do not meant to forbid comment at all, there are comments that you can add such as legal comment (creating a copyright for your code), TODO comment, or warning of consequences comment (comment that you add when you want to warn another developer about a function or class) However, most of the time you can avoid comment by applying clean code in your code.

Finally, we had arrived at the end of this article. Clean code seems like a minor task that has nothing to do with functionality. However, code is not all about functionality, it also include readability and understandability. As a closing statement, I would like to end it with this statement:

“Code is like humor. When you *have* to explain it, it’s bad” — Cory House

So what are you waiting for? Let’s create a clean code!

References

1. Martin, Robert C. (2008). Clean Code A Handbook of Agile Software Craftsmanship. Prentice Hall. 1st ed
2. What is Clean Code and why should you care? · Cvuorinen.net
3. Definition: High cohesion (educative.io)
4. A Few Principles of Clean Code (x-team.com)