One of the most discussed subjects during code reviews or in projects is not a functional thing but more a style thing: How does the code look? What coding style do we adopt?

And while it feels like mostly a cosmetic thing, the code style is actually quite important. It determines not just how you write code, but also how you can read it. And since you usually read the code a lot more often than you write it, this is quite important.

The race for shorter code

More and more I see that developers opt for the shortest bit of code they can possibly write. And PHP as a language is also changing to make things a lot shorter. Think of the Null Coalescing Assignment Operator or the Pipe Operator, for instance.

Now in essence of course, the longing for shorter code can be understood. A lazy developer is a good developer. And if anything, wanting to type less characters is a great property of a lazy developer.

Write once, read often

Up to a certain point I can follow the idea of a lazy developer. Hell, I’m a lazy developer. However, as I mentioned before, you read the code a lot more than you write it. And if you think about that, it’s much more important to optimize your code for reading than it is for writing.

Combine that with the fact that our modern tooling with IDE’s that help us write the code makes it very easy to write code. With templates, macro’s and auto-complete, we don’t actually have to type all our characters anymore. Our laziness is supported by our tooling. So is it really needed to shorten our code that much anymore?

Optimize for reading

I don’t know about you, but I spend a lot of time reading code. Whether that is brand new code or older legacy code, if I need to modernize a codebase or simply implement a new feature into some existing code, I need to write what is there, determine what it does, then make whatever change I was going to make. And usually this involves stepping into called methods to see what these do, sometimes several levels deep. The most important thing for me, therefore, is to be able to quickly read what code does. How it behaves, how it alters values, what it returns.

Let’s borrow an example from the pipe operator RFC:

function getUsers(): array {
    return [
        new User('root', isAdmin: true),
        new User('john.doe', isAdmin: false),
    ];
}
 
function isAdmin(User $user): bool {
    return $user->isAdmin;
}

So far so good, right? Two methods. Now to figure out how many users are admins, I’d write a pretty simple bit of code:

$numberOfAdmins = 0;

foreach (getUsers() as $user) {
    if (isAdmin($user) === true) {
        $numberOfAdmins++;
    }
}

The new pipe operator would turn this into the following piece of code:

$numberOfAdmins = getUsers()
    |> fn ($list) => array_filter($list, isAdmin(...)) 
    |> count(...);

Granted, this is indeed shorter. But does this really make it more readable? I understand that this is subjective, but if you just take a quick glance, which gives you more information in less time, the top or the bottom code snippet?

Let’s borrow another example from an RFC, this time the earlier references Null Coalescing Assignment Operator. This change to the PHP language is a shortening of an earlier syntax shortening. Old man speaking: Back in the old days, we’d write this bit of code as follows:

if ($this->request->data['comments']['user_id'] !== null) {
    $this->request->data['comments']['user_id'] = 'value';
}

Earlier on, this was shortened to:

$this->request->data['comments']['user_id'] = $this->request->data['comments']['user_id'] ?? 'value';

and now, it’s become:

$this->request->data['comments']['user_id'] ??= 'value';

I would like to repeat my questions from the last set of code snippets: But does this really make it more readable? I understand that this is subjective, but if you just take a quick glance, which gives you more information in less time, the top or the bottom code snippet?

And it doesn’t stop at that. I still encounter the exclamation mark a lot. For instance:

if (!$variable) {
    // do something
}

That exclamation mark is easily overlooked when quickly scanning over code. And how much more typing does it take to make this:

if ($variable === false) {
    // do something
}

Inclusive coding

Even if you don’t have an issue with reading these shorter versions, it might be good to adopt a more explicit style of coding. Because most probably, you won’t be the only person reading the code. And the shorter the code and more complex the syntax, the heavier the mental load is on developers to read the code. Not just you (or you in six months after focussing on a lot of other stuff), but also other developers (including potentially those under high stress, with mental health issues, junior developers who just don’t have that much experience yet, etc). By keeping the code explicit and basic, you help those developers understand what is happening. Doing so will make your code more inclusive.

Make your code more explicit

I would love to see more people adopting more explicit coding styles. Keep in mind that someone, possibly you, might be reading this code in a few months or years time, trying to figure out what’s going on. Do you really want them to have to take a long time to understand what is happening?