Readable code tips: Introduction

Introduction and naming with units
Extract complex conditions
Don’t inline everything

There’s lots about code that slows us down

I’ve been doing a lot of code reviews recently. And while most of the code I review works (by which I mean: meets the specification), it often takes me a long time to get to a point where I’m happy that it works.

I include as a part of my review process:

checking types (if static analysis is not done)
checking that input and output is validated and escaped (if this is not done automatically)
cross-referencing with APIs, documentation, or other parts of the code
looking for and testing for security issues
thinking about performance
considering the architecture
other things I can’t remember right now.

These things, when not automated, slow me down and require thinking.

A lot of these can be at least partially automated. If not then a lot of them are kinda “checklisty”. Hard rules that can be followed to ensure consistency.

Many of these things also slow me down when I revisit code later, or open up someone else’s code to work on it.

Yes, there are already plenty of things about code that slow us down. And they do so for good reason. This is “good friction”.

Poor code readability is bad friction

But there is an aspect of code that slows me down greatly; doesn’t seem to have much automation; and really doesn’t seem to be well understood in a lot of places. I consider it “bad friction”.

That aspect is: code readability.

And by “code readability” I don’t mean “style” as in tabs vs spaces, the casing of variable names, how long your lines are and so on that linters and formatting tools catch. I mean making your code readable and easily understandable to other humans – including your future self.

I mean things like:

Naming your variables so that they are unambiguous and clear.
Striking the right balance between inline expressions, and tons of variables.
Making conditions simple.
Using early returns/guard clauses – but not overusing them.
Understanding language and framework features properly to make things simple.

An example

As a quick example, consider variables that have units associated with them. The tip here is to add the unit to the variable name. This removes ambiguity and prevents having to look up the source of the variable to figure out what the unit is. It’s right there for you in the place that you need it.

Compare:

function applyCoupon( $couponDiscount, $price ) {
    // Is the discount a percentage, or a value?
    // Is the price in cents or dollars?
}

with:

function applyCoupon( $couponDiscountAsPercentage, $priceAsDollars ) {
    return $priceAsDollars * ( $couponDiscountAsPercentage / 100 );
}

Sure, it’s longer. But I can read this code and only this code and know exactly what is going on without having to go looking up definitions or documentation.

This really simple tip, if you can remember to do it, reduces bad friction and speeds up everyone, including your future self!

This is great! Show us more!

Yes! If you like this, I plan to present some of my code style rules for readability and I will do this over the course of my next few posts.

Or maybe: This is bad. I don’t like it!

That’s cool too. I present these tips with the clear caveat that they are my style. You may not like these ideas. That is fine because you have your own style. But I think they are simple, practical things that you can do to make your code better for people to understand.

At least be open minded, consider them. That’s all I’m asking. Or… don’t read on. You can literally close this tab now and not think about it again. Do what works for you.

Final notes and references

I see these things that come up again and again. And they seem to me to be easy to fix.

Yes, they are things that I sometimes neglect or forget to to. And yes, there are cases where they are not appropriate. But I think we are not exposed enough to other ideas about code style and readability, and we don’t think about it enough. I’m sharing some of mine to give you some ideas for your own code style.

So take them if they are helpful. Leave them if they aren’t.

My examples will be in PHP, but many of these principles apply to other languages.

This style is largely inspired by learnings from the Laravel community, who care about code style a lot. I would like to recommend that you look up the following resources for more examples and better explanations than my own:

BaseCode Field Guide: This is a short ebook that is now free. I highly recommend reading it.
Writing Readable PHP: A really quite expensive short video course. But there’s a free short email course you can sign up for too.

I don’t know when the next posts will arrive. You can follow me on Mastodon or subscribe to my RSS feed and you’ll find out when I’ve had time to write more!

Contents