SitePoint
  • Premium
  • Library
  • Community
  • Jobs
  • Blog
LoginStart Free Trial
Clean Code in PHP
Clean Code in PHP
Clean Code in PHP
Contributors
About the authors
About the reviewers
Preface
Who this book is for
What this book covers
To get the most out of this book
Download the example code files
Download the color images
Conventions used
Get in touch
Share Your Thoughts
Part 1 – Introducing Clean Code
What Is Clean Code and Why Should You Care?
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
Summary
Who decides these things anyway?
Best practices – where do they really come from?
Design pattern principles
Being context-aware
Being consistent – get results quicker
About source code analysis tools
About testing and its multiple forms
Summary
Understanding code
A bit of history
The purpose of code
Be understood, not clever
A note on maintainability
Using binary operators and octal, hexadecimal, and binary notations
Assigning a variable and using gotos
Excessively using comments
Using ternary comparisons
Using abbreviations
Bringing micro-optimizations to your code
Recoding the methods of the SPL
Summary
PHP as an ecosystem
Choosing the right libraries
A word about semantic versioning
What is semantic versioning?
How to deal with semantic versioning
Stability versus trends
Summary
Naming and organizational conventions
Class files and interface files
Executables
Web assets and resources
Naming classes, interfaces, and methods
Naming folders
Separating responsibilities
Event dispatching
Demystifying polymorphism – interfaces and abstract classes
Interfaces
Abstract classes
Summary
Old versus new PHP
Strict typing
Error reporting
Attributes
The version 8 revolution
Match syntax
Named arguments
Read-only classes and properties
Migrating resources to proper classes
Protecting your sensitive arguments from leaking
Summary
Part 2 – Maintaining Code Quality
Technical requirements
Syntax checking and code styling
The PHP built-in linter
PHP CS Fixer: a code sniffer
Static Code Analysis
phpcpd – the copy and paste detector
PHPMD: the PHP mess detector
PHPStan – a static analyzer for PHP
Psalm: A PHP static analysis linting machine
IDE extensions
PHP Inspections (EA Extended)
Intelephense
Summary
Further reading
Technical requirements
Introducing code quality metrics
Aspects of software quality
Code quality metrics
Gathering metrics in PHP
phploc
PHP Depend
PhpMetrics
The pros and cons of using metrics
The pros
The cons
Summary
Further reading
Technical requirements
Installing code quality tools using Composer
Installing code quality tools using require-dev
Global installation
Composer scripts
Installing code quality tools as phar files
Keeping your phar files organized
Managing phar files using Phive
Adding Phive to your project
Summary
Technical requirements
Why you need automated tests
Easier refactoring with tests
Types of automated tests
Unit tests
Integration tests
E2E tests
The testing pyramid in practice
About code coverage
Understanding code coverage
How to generate code coverage reports
Using the @covers annotation
What to test
Summary
Further reading
Technical requirements
Why you need CI
The costs of a bug
How to prevent bugs
Introducing CI
The build pipeline
Stage 1: Build project
Stage 2 – Code analysis
Stage 3 – Tests
Stage 4 – Deploy
Integrating the pipeline into your workflow
Building a pipeline with GitHub Actions
GitHub Actions in a nutshell
Stage 1 – Build project
Stage 2 – Code analysis
Stage 3 – Tests
Stage 4 – Deploy
Integrating the pipeline into your workflow
Your local pipeline – Git hooks
Setting up Git hooks
Git hooks in practice
Advanced usage
Excursion – Adding CI to existing software
Step by step
An outlook on CD
Summary
Further reading
Technical requirements
Coding standards
Going with existing standards
Coding guidelines
Examples of coding guidelines
Setting up guidelines
Code reviews
Why you should do code reviews
What code reviews should cover
Best practices for code reviews
Ensuring code reviews are done
Definition of done
Code reviews conclusion
Design patterns
Understanding design patterns
Common design patterns in PHP
Anti-patterns
Summary
Further reading
Technical requirements
Why documentation matters
Why documentation is important
Developer documentation
Creating documentation
Text documents
Diagrams
Documentation generators
Inline documentation
Annotations are no code
Unreadable code
Outdated comments
Useless comments
Wrong or useless DocBlocks
TODO comments
When commenting is useful
Tests as documentation
Summary
Further reading
Why subscribe?
Packt is searching for authors like you

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.

End of PreviewSign Up to unlock the rest of this title.

Community Questions