The importance of clean code in teams

The onboarding process is never easy. You are getting into a new project, and many people around you are already familiar with it. You must learn everything: who does what in the team, what the exact requirements are, the technical challenges the team has been through, and what is coming next. This process can last several weeks, and even several months in some cases (it can also last for more than a year on some gigantic legacy projects, but that is another subject). If you can save yourself the process of learning the coding conventions because you already know them thanks to clean-code principles, then it is one thing you will not have to think about and you can focus on other things.

Being able to write clean code is like speaking fluently in the same language as the other people in the team: it makes it easier to communicate and write code in the same way without noticing who has written which part.

Clean code will help you with code longevity. When working as a team on a project, there are great chances the source code will be maintained for at least a few years. The code will continue to be maintained years after your departure. It is important to do things right because you will not be here forever to explain everything you did to the person still working on the project.

Writing code cleanly will avoid the apparition of what we call single points of failure (SPOFs). These SPOFs are the worst nightmare for any project. They are also symptomatic of legacy projects. They can be described as an entity (a developer, a technology, a library, and so on) that holds the whole project by itself. If this entity fails, everything crumbles.

A concrete example of an entity failing is the departure of a developer. If they are the only person to utterly understand how the project works and is considered the “superhero” of the project, then it is a big problem. This means the project will not be able to continue without them, and it will be an absolute pain to maintain the project after their departure.

One excellent example of SPoF avoidance was given by Fabien Potencier, the creator of the Symfony framework, during the SymfonyWorld Online 2021 Winter Edition convention. Even if Symfony is an open source project, he has been the person working the most on it since its creation. He explained during a conference that one of his main tasks now is to transmit the maximum amount of knowledge about the framework to the maximum number of people so that Symfony does not rely on him exclusively anymore. He absolutely wants to avoid being the SPOF of Symfony, and naturally wants Symfony to be maintained and developed, even after he’s no longer working on it himself anymore.

One of the numerous ways to avoid this problem is by writing clear, concise, and understandable code—writing code in a way everybody can easily understand what is happening. After getting into this book, you may have a better idea of how to achieve this.

Talking about teamwork, another critical point is code reviews. Even if we will be getting into the details of these later in this book, let’s talk about them quickly here. If you have never heard of a code review, it is simply a process where other developers of the projects are reviewing, reading, and commenting on the changes you want to bring to the code base. This process is mandatory in most open source projects and highly recommended for any project, given the benefits it brings. You can now easily imagine that if everyone has their own way to write code, those reviews are going to take way longer. This goes from the way you format your code or how you separate files, classes, and so on. If we all speak the same language, then we can focus on things that really matter during the code review: if the functional need is respected, whether there are any bugs, and so on.

We will see in the next chapters that clean-code definition often depends on the team you are working with. Even if there are some general rules, it mostly depends on what the developers you are working with are used to. Again, the reason is habits but also consistency. This way, the team can work faster and better together.

If you happen to work in an area where several teams are gathered in the same place, you will inevitably notice that each team has its own set of rules that works well for them, but also common rules that will allow you to talk with everyone in the same language. Because solutions to your problems are not always found in your direct team but sometimes also from people surrounding you without working with you on the same project directly, it will be so much easier to help each other if basic rules are shared between groups of people.