Clean Code Practices for Software Development Success

Why Clean Code is Crucial in Software Development

Clean code is critical in the software industry as it is perceived as what makes or breaks a project. Startups and companies have shut down because of the insurmountable technical debt that unclean code has brought them.

“He who has a why to live for can bear almost any how” is a very well-known quote from Friedrich Nietzsche’s Twilight of the Idols.

When people have ingrained a habit, it is very hard to break them. The best way is to make them want to change by showing that it is in their best interest to do so. This is why I’m starting this article with an explanation on the importance of clean code in our application and by dismantling a few misconceptions in our work as software developers.

The Importance of Code Readability in Software Development

Programmers think they spend most of their time writing code when, in reality, they spend a lot more time reading and reviewing code, documenting, figuring out what to do and how to do it, debugging, etc.

When we optimize something, we start with what is easy to change, will take less time to modify, and will have the most impact.

This is why I think that to become more efficient, we should not only improve the readability of the code we type, but also of the documentation we write, and choose tools, packages, and technologies that follow the same principles.

How Code Complexity Impacts Development Time and Costs

Another big misconception is that the code we type is the core value of our product, when in fact, the real value of the product is its final, working state. The code is just a medium we use to translate an idea into a thing with which we can interact.

If we could program machines by casually talking to them or with natural written language, which may become possible in a few dozen years, it would be far more convenient and faster.

But until that happens, with every line of code we add to an application, we take the risk of adding bugs, doing more testing, and failure. So the code actually feeds on our time.

To reduce that loss, we need to write less code but with more value—something for which we, as software developers, are paid.

Managing Code Complexity to Reduce Costs in Software Projects

Here, I will diverge a bit and talk about the concept of MVP.

MVP, or Minimum Viable Product, is one of those terms that are as heavily marketed as they are corrupted. Behind this concept lay 3 ideas:

Perfect ergonomics
Minimal features
Awesome feedbacks loop

Building a good product is about removing everything bad and keeping only what is perfect. And only the users and clients know what’s good and what’s bad.

It is the same for code. We want to keep only the code that gives the most value to the application and get rid of everything else.

By doing so, we not only lower the cost of production and maintenance but also of infrastructure.

The Ripple Effect of Bad Code on Software Performance

Let’s take a look at this graph for a moment:

As developers, we are on the front line. Bad code will just roll downhill and negatively affect every other aspect of the product.

For example, when we find out our app is running very slowly or when it freezes during traffic peaks, what are the solutions? More servers? More scalability? More cache?

Are those really solutions? It sounds like sweeping the mess under the rug to me.

From day one, we speak about scalability and caching, but we never speak about writing efficient code. The fact is, by writing efficient code, we reduce if not entirely remove the need for scalability.

That is the real problem. The code sucks, the database is not optimized, the technologies are not well chosen. It doesn’t take more time to do it well; it only takes more brainpower.

Brainpower is not free, for sure, but down the road (or the pipe?), it is going to be much cheaper—especially if the company is about to go bankrupt because of technical debt.

For some sage tips on how to write code the right way, you should check out the 8 Golden principles when writing Code.

The Long-Term Impact of Bad Code on Software Maintenance

When we have an injury or catch a cold, some rest, lots of water, and time will do the job. Same goes for a broken heart (although drinking a lot will not help).

Time has that incredible healing power.

Unfortunately, time also has an incredible power to destroy. As developers, we know that time is not going to heal our bad code. If from day one we clog the pipe with bad decisions, impossible deadlines, wrong technologies, and badly written code, it is going to haunt us forever and never going to get better. See how you can avoid hiring bad programmers.

Defining Clean Code: Key Characteristics and Best Practices

Now that we know why we should write clean code, the question remains: what is clean code?

Even if we code the machine to execute our tasks, the code should be readable to humans first. It should be simple and easy to follow, its scope isolated, easily testable, and well documented or self-documented.

To quote Martin Fowler: “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

We have to remember that we are writing code for people.

Imagine a web designer creating art that no developer can build, or a manager creating a process so painful and complicated that people don't want to follow, or a superior giving orders that no one can reasonably comply.

Then I guess we know who the fool is, right?

How to Write Clean Code

I didn’t start with explaining how to write clean code because most developers already know it, or they have at least heard of some concepts that help writing clean code.

Essential Clean Code Principles for Every Developer

To write clean code, we should first stop ignoring the clichés—because they work! We should push ourselves to revisit and apply them daily.

If you still don't know what I am talking about, here’s a list of the clichés you can look up:

DRY – Don't repeat yourself.
KISS – Keep it simple, stupid.
YAGNI – You ain’t gonna need it.
SOLID – Design principles, this is a topic in itself but mastering the S will already help us in a tremendous way.
MVC – Architecture principle, Model View Controller.
Design Patterns – There are tons of design patterns out there, some people already resolved our problem.
Coding Standards/Conventions – So we don't end up having different code with different coding styles among our team.
RASAP – Refactor as soon as possible. Don't clog the shit pipe, clean it as soon as possible!
Don't reinvent the wheel – There are already tons of libraries that can help solve our problems so we don't have to do it again.

Building Habits for Writing Clean Code

Now that we know the theory, the hard part is to apply it. Creating small, repeatable mind patterns that we can apply whenever we type some code is the secret.

For example, when we create a file or directory, we check the naming convention and if there are too many. If so, we rename it or create a subdirectory.

When we create a class, we check the naming convention, too. We make sure it follows some logic and gives a good description of the responsibility of that class.

When we create a database request, we make sure that the indexes are well set, see if we could simplify it or make it more efficient, etc.

When we already copy-pasted some piece of code two or three times, that’s a good moment to do some thinking.

These mind patterns come with experience but only if we love efficiency. They will not automagically apply to our code; we have to push ourselves to do it.

Trust Your Instincts: Identifying and Correcting Code Issues

Our gut feeling tells us when something is wrong. That feeling we have in our stomach is also useful while we code.

When we...

feel like it’s wrong,
feel like it’s too complex,
cannot understand what we did any longer,
feel like it’s not the best way to do it,

feel like we’re being lazy,

...we need to STOP! Think about it for 5 minutes and refine what we’re doing because our gut is probably right.

Coding is not about production; it’s about craftsmanship. It’s done with pride, professionalism, mastery, and purpose. It’s not about how many lines of code we produce; it’s the quality of code that makes us good developers.

Mastering the Tools for Clean Code in Software Development

We don't need fancy tools; we need efficient tools.

As programmers, we need to master a few languages. Our programming languages of choice are our main tools. Whether it’s PHP, Python, Javascript, or C#, it doesn’t really matter. We can just stick with one or two and master them.

The same story applies to frameworks. We don't need to know every single framework on the planet. We can choose a few that best suit us, and master them.

Useful tools, such as code formatters, code linters, and debuggers, help us a lot. Most of these are provided by the respective IDEs that we use, and it’s important to use them constantly.

Essential Reminders for Writing Clean, Efficient Code

Keep it simple and readable to others.
Refactor as soon as possible.
Don't be the one who clogs the shit pipe; do some honest introspection.
Take the time to learn the clichés.
Improve every day.

As software engineers, our craft is to write efficient code.

Sometimes we get carried away by the hype of new technologies, languages, and frameworks (especially those of Javascript) that we forget that some skills are perennial and can be applied to any language. By acquiring and applying them, we become a lot more valuable than by learning a new framework.

Sources

This article is based on other blog articles and books I have read. A few of them are:

The Importance of Clean Code (and How to Apply it in Your Software Projects)