Siprak Team
Published in

Siprak Team

Clean your code!

What does the title mean?

The word clean, according to Merriam-Webster means, to rid of dirt, impurities, or extraneous matter or to rid of corruption. Then, what does code cleaning means? To clean our code means to get rid of impurities, “dirt”, or corruption from our code.

There are actually several terms as the alternatives of impurities which are code smells, bad codes, dirty codes, etc. In this article, I will stick with the term dirty codes, but do not be confused if you found other terms. It usually means the same things.

“Clean code is code that has been taken care of. Someone has taken the time to keep it simple and orderly. They have paid appropriate attention to details. They have cared.”

— Robert C. Martin

What are those dirty codes?

First, dirty codes are codes that are hardly understood. A code is considered dirty if it satisfies one of the following statements:

  1. The execution flow or how different objects collaborate is hardly understood.
  2. The role and responsibility of the class(es) are hardly understood.
  3. The purpose of the method(s) is hardly understood.
  4. The purpose of the variable(s) is hardly understood.
  5. The purpose of the expression(s) is hardly understood.
  6. And other statements that make the code hardly understood.

Second, dirty codes are codes that are nonadaptive to changes. A code is considered dirty if it satisfies one of the following statements:

  1. It has duplication of codes.
  2. Classes and methods have more than one responsibility.
  3. Classes and methods are tightly coupled and low cohesion.
  4. It has an inefficient number of classes and methods.
  5. It has no tests, or
  6. The tests are hardly understood and hard to change.

Why do we have to clean our code?

Making the code easily understood by other people. Most of the time, developers read to understand the existing code and then write their improvements. Hence, the code easily understood may help them to understand it easily and may increase the speed of development.

It will also help you to understand your own code easily. Commonly, developers develop many applications at once. Hence, they may forget how some of what they have written and have to reread them.

“If you want your code to be easy to write, make it easy to read.”

— Robert C. Martin

Principles for a clean code

I have this project that I am currently developing called Sistem Informasi Penilaian & Database Praktikum. The project uses Django (Python) and ReactJS (JavaScript) as the main frameworks. I am going to use that project as an example of the principles below.

Proper Naming

The names of entities (classes, methods, variables, etc.) should be descriptive and meaningful. The name should represent the usage or purpose of the entity.

The names of entities (classes, methods, variables, etc.) should be searchable and unambiguous. The name should be specific. For example, naming a variable button is a bad one because there may be many other variables named button in that code. Change it to loginButton, etc.

Replace magic numbers with named constants. For example, in a method that returns the value of the area of a circle. the π (pi) value should be defined in a variable named PI_VALUE at the start of the method and the next lines should use that variable instead of 3.14.

Class Names — Name of classes and object should be a noun, such as Administrator, Role, Notification, etc.

Django Models

Method Names — Name of methods should be a verb handleClick, validateField, fetchData, etc.

Proper Methods

In a clean code, a method should be/have:

  1. Small,
  2. Only does one thing or responsibility (Single-responsibility principle),
  3. Avoiding using the flag parameter, having a boolean type parameter,
  4. Not returning null,
  5. Few parameters (preferred).

Commenting

A code should be self-explanatory without the help of comments. Although, you can still use comments for things, such as an explanation of intent, clarification of code, and warning of consequences.

There are five things we have to do to achieve a clean code in commenting:

  1. Don’t be redundant
  2. Don’t add obvious noise
  3. Don’t use closing brace comments
  4. Don’t comment out code
Bad comments

Source Code Structure

  1. Every line should be short.
  2. Related code should be together and blank line(s) is/are used to separate weakly related code.
  3. Variables are declared close to their usage.
  4. Each method should be separated vertically.
  5. Dependent and similar methods should be close and the if a function calls another function, the caller should be on top of the callee.

Don’t Repeat Yourself (DRY)

DRY means avoid duplication anywhere in our code. We should have not the same piece of code in different places. Using this principle improves the code’s adaptability to changes. If changes are needed, we can just change it in one place, rather than change it in every piece of the code.

To change the entire RoleButton, I just need to change at one location (left picture).

SOLID

SOLID is an acronym. It is the core principle of Object-Oriented Programming. S stands for Single-responsibility principle. O stands for Open–closed principle. L stands for the Liskov substitution principle. I stands for Interface segregation principle. D stands for Dependency inversion principle. I am not going to explain it here to keep the length of this article short.

Design Patterns

Design Pattern is a layout or scheme of entities (class, methods, etc.) that are established to solve a reoccurring problem in object-oriented programming. It is a reusable solution for a specific problem. Design patterns are classified to four: creational patterns, structural patterns, behavioural patterns, and concurrency patterns.

Refactoring Guru has provided us with explanations of design pattern and the code examples in many languages. You can check it out in the link below.

Tests

Clean code should have tests that follow the FIRST principles.

  1. Fast — It should be run quickly.
  2. Independent — No dependencies between tests
  3. Repeatable — Tests should be able to be run in any environment and computers.
  4. Self-Validating — Tests should automatically validate itself whether they pass or fail. You should not need to check manually.
  5. Timely — Tests need to be written in a certain time in the development cycle. in TDD, developers write the tests first before developing the application.

Are we done?

No! This is just a summary of the clean code topic and it does not cover everything about the topic. Most of this information is gotten from articles that summarized a book called Clean Code by Robert Cecil Martin. Many developers recommend that book as it is considered as the main resource to learn about the Clean Code topic. Read it!

References

Clean Code by Robert C. Martin

https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29

 by the author.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store