What Is Clean Code and Why Should You Care?

Part 1 – Introducing Clean Code

The purpose of this first part is to introduce the concepts of clean code and the theory behind it. This part is intended to be quite theoretical, although concrete examples will be discussed as the chapters progress. The first approach of clean code is proposed in order to explain its usefulness and why it is necessary in the life of a developer.

This section comprises the following chapters:

• Chapter 1, What Is Clean Code and Why Should You Care?
• Chapter 2, Who Gets to Decide What “Good Practices” Are?
• Chapter 3, Code, Don’t Do Stunts
• Chapter 4, It Is about More Than Just Code
• Chapter 5, Optimizing Your Time and Separating Responsibilities
• Chapter 6, PHP Is Evolving: Deprecations and Revolutions

What Is Clean Code and Why Should You Care?

If you are new to PHP: Hypertext Preprocessor (PHP) and software development in general, there’s a good chance you haven’t come across clean code yet. We all began here; everybody must be aware of this. Clean code is more than just a set of rules. It is a real mindset—a way of thinking about what you are creating.

We often come across developers that have been in information technology (IT) for many years, even decades, and never had to worry about clean code. This may be for several reasons for this: working alone on a project for many years or developing on a legacy code base are a few of many reasons “clean code” did not reach their ears or wasn’t one of their concerns.

Become aware of clean code—the earlier the better. As with many other habits, once you have adopted a way of working with code, it is difficult to change this. It may be because you are not convinced at all about what clean code is about, you are not sure it applies to you, or you may just be lazy about applying new “rules” because yours are already working for you (be assured that everyone’s been through this). But if you care about it and you are taking note—well, you’ve already done the hardest part, because this means that you are ready to change your habits. Don’t misunderstand us—the point is not to change everything you’ve learned up to now; it’s more a case of improving the skills you already have.

You may not be aware of this, but it is pretty certain that you already have some habits that totally suit clean-code principles and that are natural to you and completely new to other developers. You should note that the goal of clean-code principles is not to be controversial at all.

The main topics we’ll cover in this chapter are listed here:

• What this book will cover
• Understanding what clean code is
• The importance of clean code in teams
• The importance of clean code in personal projects

What this book will cover

You may have already heard about software craftsmanship books, clean-code books, and so on. What is the difference between this book and other ones? Well, we realized when we are a neophyte in development and discovering new programming languages, or even getting into programming and source code for the first time, it may be hard to understand how to apply these principles you read about everywhere. Programming languages do not all offer the same features—some are evolving fast, while some are not evolving anymore. Notions and the way things are named in one language may not be valid in other languages. That is why this book focuses on clean code in PHP especially.

You will not have to think about how to implement these principles and rules in PHP, which is something less to remember when absorbing knowledge. You will find examples and tools applying directly to you, used in professional projects, and proven by the industry. This way, we can get straight to the important points we would like you to understand. You can put your knowledge into practice immediately while reading this book and as a result, learn faster. Additionally, you do not need 10+ years’ experience to understand what will be shown. Only basic knowledge of PHP is required to fully understand what will be exposed.

This book is a compilation of years of experience—years of practice in the field, faced with real problems that had to be solved according to technical constraints, functional constraints, and time and money constraints. This will not be yet another book full of utopian principles that cannot be applied in real life.

More than fitting directly to your environment by talking about PHP only, this book can be read in the order you want. It is divided into two distinct parts. The first one (which you are currently reading) will expose a bit of theory about what is clean code and what are basic principles of it, directly applied to the PHP language up to version 8.2, and so on. The second part will be focused on practical tools you can use to ensure you are following the right rules the correct way, setting up an environment and your integrated development environment (IDE) in order to be as efficient and clean as possible, and getting metrics on your code, automated testing, writing documentation, and more. This means you can skip parts, take them in the order you want, and learn at the speed you want.

You will not have to read the whole theoretical part before getting into practice—you can dive into tools and concrete examples right now. You can also focus on the first part before getting into the practical aspects in order to be sure you fully understand what will be explained later. It is up to you.

Understanding what clean code is

Clean code is the act of writing code by thinking of the future—that is, thinking of the people who will collaborate with you or on the project without you. And when we are talking about “the people who will collaborate with you”, this may even be yourself. If you never did, you should try to read and maintain the source code you wrote a few months (or years) ago. Isn’t it challenging? Well, do not worry—it is hard for everyone. You will surely find this complicated for many years, and there is no quick fix to this. It is the same process for everyone.

There are many reasons for this, as outlined here:

• You are still learning new ways to code every day
• You are practicing and you’re getting better at coding
• Your way of thinking may be evolving because of the people you meet or simply because you are getting older
• Innovative technologies and libraries are released every day, and some ways of doing precise tasks are getting deprecated
• The language you are working with (here, PHP) is evolving and new standards are appearing

Talking about PHP, it is remarkably interesting to see the language is evolving greatly and quickly these last few years. Many called for the death of PHP a few years ago. It is true that before PHP 7, the language was truly not going well. PHP 7 and newer versions are a huge breath of pure air for us. New versions are being released frequently and features are being added to PHP (just look at the match expression and the support of enumerations in PHP 8.1!). Strict typing has also been introduced, which is a gigantic step forward too. We will dive into PHP evolutions that ease the writing of clean code later.

It does not really matter which programming language you are using—undeniably, you will get scared each time you look at some old code you did yourself. Writing your code in a “clean” way will help you to minimize this effect and understand it better, instantly, years later. By doing this, you are giving yourself a treat, because you will be coding in a way you are more and more used to—a way of writing many people are used to.

It may be the most impressive thing about clean code: it does not matter which technology you are using, which library, or even which language. It does not depend on the country you are living in and it does not depend on your years of experience, or even if you are coding for a living or as a hobby without financial intentions behind it. Clean code is a skill that at some point, every developer will improve at and face in their life. Of course, you will get better at it if you focus on it, but just learning from your experience of what works and what does not in an IT project is already, in a way, learning clean code. More than the rules, tools, and tips you will find in this book, clean code is a question of experience and years of practice. During your developer career, you will meet different challenges and diverse ways of thinking by meeting people and collaborating with numerous different teams.

You should always remember that coding is a team job. It is rare now to work alone on a project without the intervention of other developers—if it still happens at all. It may be a professional project, an open source project, or even a private personal project. Saying that other developers will help with your project does not necessarily mean that they will write some code. They can also try to find solutions with you to the technical challenges you will be facing, and that applies to every type of project.

In any case, doing things properly will ease a crucial step we all go through when getting into a new project: the onboarding process.

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.

The importance of clean code in personal projects

You may think that clean code is less important for personal projects, even just a tiny bit. You would be wrong if you think like this for many reasons, as set out here:

• How can you be sure that nobody will ever be involved in the development in the future?
• If you make your project open source, don’t you want the world to see that you are coding cleanly and be proud of this?
• You will probably want to improve your project repeatedly. If you write bad foundations, it will be a nightmare to maintain and add new things without the fear of breaking anything. Sometimes, it is impossible to add new features because of bad code writing. In the worst cases, you will have to entirely rewrite your application. You do not want to do that.

As mentioned earlier, try to read the code you wrote a few years ago. There’s a great chance you will not be able to understand briefly what you wanted to do at that time. You may think the comments you put (if you do this) are here to help, but let’s ask two questions, as follows:

• Who truly reads code comments?
• What about writing code in a way that comments are unnecessary, and it is so clearly written it can be read like a book?

This is what it is all about: being able to read the source code like simple sentences without having to stop on a line to understand it. Also, to repeat what was said about clean code in teams: just because you are creating a project on your own does not mean that you won’t need external help. In fact, it is almost a certainty that one day, you will need the help of someone for something. Again, if you share the same set of common rules, it will be much easier for the helper to bring in their ideas. Even in personal moments and projects, a developer’s job is teamwork. Always.

Clean code is a mindset, and this mindset includes being proud of what we created—the taste of a job well done. It will maybe take a few years to fully understand what it is all about, and we always have new things to learn and situations we are facing for the first time. Clean code is to move toward the moment when you look at your code and tell yourself you are completely relaxed about showing your code to anybody.

As the saying goes, “write code as if the next developer to run it knows your address”. And this should also apply to personal projects because you are that very next developer.

Summary

Are we done yet with the theory? Well, kind of. We defined together what clean code consists of. We gave a mutual definition of clean code. By having the same definition of clean code, we are one step deeper into it, and ready to dive into more advanced principles in the next section.

But of course, we are not done yet. Even if you agree with the definition we presented, you may of course have a lot of questions already. And the most important questions should be the following: Who decides these rules for you? Who has the power to impose this vision? This is what we are going to see together in the next chapter.