Clean Code Principles: Key Practices for Writing Readable and Maintainable Code

Designing your code structure is an art and there is no doubt about that. I will talk in this article about some principles that have been given some cool names, these principles are too essential for development, however, all clean code principles are about achieving higher goals which are achieving reviewability, maintainability, and reusability.

What is clean code?

Clean code is not a set of strict rules. It is a set of principles for writing code that is easy to understand and modify. In this case, “understandable” means that the code can be immediately understood by any experienced developer. The following characteristics of clean code are what make it easy to read:

• The entire application’s order of execution is logical and clearly structured.
• The connection between different parts of the code is quite obvious.
• The task or role of each class, function, method, and variable is immediately understandable.

Code is easy to modify if it can be adapted and extended. This also makes it easier to correct errors in the code. Clean code is thus very easy to maintain. Easily modifiable code has the following characteristics:

• Classes and methods are small and only have one single task.
• Classes and methods are predictable, work as expected, and are publicly available through well-documented APIs (interfaces).
• The code uses unit tests.

Why does Clean Coding matter?

The cost of “dirty” code compounds over time, with each future task taking hours longer than necessary as programmers muddle through a confusing codebase. It’s not just cost savings, either. Clean coding improves dependability, extensibility, and performance all around. One developer taking their time to write good, tested, comprehensible code will save countless hours, days, and weeks in the time to follow.

In other words, clean code applied to a project offers advantages like:

• Clean code is easier to read, and therefore easier to change down the line
• Clean code is thoroughly tested, which means it is more dependable and fully functional from day one
• Clean code can be refactored over time with less effort, meaning that teams are less likely to rewrite from the ground up

Principle of Clean Code

Let’s discuss some principles that have been given some cool names, these principles are too essential for the software development

KISS

KISS is an acronym for “Keep It Simple, Stupid”. It’s a software design principle that focuses on making code as simple as possible so the project will be simpler to maintain. Maintainability is not just nice to have, it’s mandatory because a lot of reasons:

• Complex code will increase the time needed for developers to implement new features, do refactoring, and understand the code. Which means increasing the costs.
• Complex code will level down the code quality and will lead to more bugs, more workarounds, more repetitive codes, and less reusability.
• Sometimes startups are dropping their old products and creating new ones from scratch just because they didn’t put in mind maintainability from the beginning and they reached a point where the best solution is just to abandon these old products.
• Developers have feelings and need to be happy to be productive, I think the worst job for a developer is to maintain an old project that is not maintainable 🙂

KISS does not come alone, but tightly coupled with two other concepts, we can consider KISS as the generic idea, and DRY and YAGNI are sub-topics that lead to KISS. But of course, there are other tactics that help to achieve KISS. But usually, if the developer put KISS into consideration when developing the code, then by nature he will find new tactics for more simplicity.

DRY

DRY is an acronym for “Don’t Repeat Yourself”. It’s another software design principle that is aimed at reducing the repetition of software patterns. Whenever you find that you are repeating your code, that means there is an abstract way to avoid that. DRY states that:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system

-formulated by Andy Hunt and Dave Thomas in their book The Pragmatic Programmer.

YAGNI

YAGNI is an acronym for “You Aren’t Gonna Need It”. It’s another software design principle that states implementing things just when you actually need them. And remove any things that are not needed. YAGNI is one of the key principles of Extreme Programming that emphasizes the importance of implementing things when you actually need them.

With this principle, you minimize the amount of unnecessary work, which is crucial for the developer’s productivity and software simplicity. YAGNI is about just-in-time manufacturing. Don’t implement features that may be needed in the future, they are expensive, time-consuming, and probably will be a waste of resources.

Bits of Advice

I will suggest next some points that I believe are important to take into consideration when building up your project:

• Functions should have single responsibility that can be understood from the name of the function.
• Avoid being a nester (Adding inner blocks to a function), and use extraction and inversion to refactor and simplify your functions.
• In TypeScript or in other languages where you can apply that, convert functions arguments with more than three arguments into an object, it will be more readable when it’s called.
• Pretty more readable, right? Especially for the developer who wants to understand what he is passing when using the function without returning to the function definition.
• Avoid for loops and while loops when you can use “for each”
• Separate all constants, enums, and configurations in independent files with clear names.
• Try to be consistent and clear when applying design patterns inside your code.
• Try to use famous frameworks whenever possible, and don’t write utilities from scratch when the community already solved that through a library.
• Try to use a common folder structure.
• Try to use common software layers, and naming conventions.
• Document exceptional cases whenever possible.
• Don’t put unrelated functions in the same file.
• Don’t put multiple components or classes in the same file.
• Try to have as small components as possible, the same case for classes, usually, a code file should not exceed 500 lines.