Development, Continuous Integration — Clean Code

Hi everyone! In this blog post, I want to explain to you all about my understanding of clean code and how I implemented it in the software engineering project.

What is Clean Code?

Clean Code

Clean code is subjective and each developer has a personal opinion. There are some ideas that are considered as the best practices and what constitutes a clean code, however, there is no determined, distinctive definition of what clean code is.

In my opinion, after reading a few books and articles about clean code, clean code can be summarized into one sentence, which is: clean code is code that is easy to understand and easy to change.

Easy to understand means that the code is easy to read, whether the reader is the author of the code or someone else. The meaning of the code is clear so it minimizes the need for guesswork and possibility for misunderstandings. The code is also easy to understand on every level, such as:

• It is easy to understand the execution flow of the entire application.
• It is easy to understand how different objects collaborate with each other.
• It is easy to understand the role and responsibility of each class.
• It is easy to understand what each method does.
• It is easy to understand what is the purpose of each expression and variable.

Easy to change means that the code is easy to extend and refactor, and it is easy to fix bugs in the codebase. This can be achieved if the person making the changes understands the code and also feels confident that the changes introduced in the code do not break any existing functionality. For the code to be easy to change, there are some ways to do it, such as:

• Classes and methods are small and only have a single responsibility.
• Classes have clear and concise public APIs.
• Classes and methods are predictable and work as expected.
• The code is easily testable and has unit tests (or it is easy to write the tests).
• Tests are easy to understand and easy to change.

Some Best Practices of Clean Code

Best Practices of Clean Code

Meaningful Names

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent. For example:

int d; // elapsed time in days

vs

int elapsedTimeInDays;

In the example above, the first declaration of a variable is not a good example of how to declare a variable according to clean code because it does not reveal what is the intent of the variable. The second declaration of a variable is the better one.

Function

In clean code, a function should be:

• Small.
• Do one thing.
• Use descriptive names.
• Have no side effects.
• Command query separation.

Example of a function that does one thing

Comments

Quote about bad code

When can we write comments?

• Legal Comments
• Informative Comments
• Explanation of Intent
• Clarification
• Warning of Consequences
• TODO Comments
• Amplification

Bad Comments

• Mumbling
• Redundant Comments
• Misleading Comments
• Mandated Comments
• Journal Comments
• Noisy Comments
• Scary Comments

Examples:

Examples of bad comments

Commented-Out Code

Do not commented-out code. For example:

Example of commented out code

How I Implemented Clean Code in the Software Engineering Project

In the Software Engineering project, I have implemented some of the best practices of clean code such as making meaningful names for the variables and functions, making the functions to do one thing, and remove unnecessary comments.

Conclusion

In my opinion, clean code is important for developers to understand so that they can make their code easy to understand and easy to change for other developers.

Thank you for reading :)