The art of writing highly readable code

Hi guys,

This topic is around for ages, a lot of books out there too. But don't get it too complicated.

I'll add my exp here to share with you guys for this. And it've been my style for years (from my first company til now).

Coding is just as same as writing an essay/story. Fascinating code would help people a lot, they would read the code with joy, learn much things as fast as they can and then jump into the development process. Win-win, isn't it?

Not only reading, but also maintaining wouldn't be a pain in the ass.

Bad code, bad stories won't get us anywhere, people hates it and so do I.

Follow General Approaches

SOLID
KISS - "Keep it simple, stupid" "Keep it short, simple"
DRY - Don't repeat yourself

Conventions

Yes, every project should have its own conventions.

Not only you would follow the language's conventions (eg for PHP, we have PSR) but also, create a list of conventions for your own project.

With this way, people must follow the overall goal for the project.

Indeed, IRL working environment, everyone has their own styles. But if somebody doesn't follow the conventions, others won't too => Creating a big mess in the project. Always try to avoid that.

Have something against the conventions? You can always raise it with the What, the Why. If corrects, the team would agree and update it.

Naming matters

Better names for everything would give clearer context for the reader when reading any kinds of code (libraries, business logic,...)

I've working with some guys and they think naming doesn't matter. Well, they fk' do.

Don't be selfish. What if you left the company, then somebody got assigned to maintain your code or fixing bugs. With bad code, it would make their lives harder and harder. They have to read it multiple times (even hundred) to know what it is doing,...

Variables

Giving a beautiful name with full details for a variable, people would catch up quickly and know the context of the methods/flows that they're reading.

Don't use short names or some mysterious code.

Good:

$scheduledPayment = $this->getScheduledPayment();
$nextPaymentDate = $this->getNextPaymentDate();
$isPaymentValidForTransfer = $this->validate($scheduledPayment);

if (!$isPaymentValidForTransfer) {
    return $this->setError(...);
}

Bad:

$next = $this->getScheduledPayment(); // ?? lol what is next?
$repo = new AccountRepository();

Methods

We all learn at school that methods/functions are the action to handle something.

Then, Action must always start with the "verb".

For methods that return boolean , no "verb" needed but you need to add the is do has,... for them.

// Good
function setUser(): void;
function resolveAccount(): Account;
function getAccount(): Account;
function handleSendPayment(): Payment;
function getAllowedClasses(): array;
function hasFirstPayment(): boolean;

// bad
function user(): User;
function allows(): array; // avoid this

Types

Always use type as many as possible, especially for languages like PHP (pretty dynamic). For JS, use TypeScript.

Not only IDE-friendly but also make your applications stricter. And it would generate huge readability, since looking at any methods, we can know the:

Params' types
Return type

Try to avoid mixed (or any)

Truthy-first

Simply convert things to positive form, eg:

isActive
canTransfer
isEligibleToReceivePayment
...

Highly increase the readability. And when you need the negative, simply put the ! above.

You don't want to mess up with the ! when using negative form.

Code things in negative form won't help you and your project to scale. It will slow you down eventually.

Stylin'

Don't do many things under 1 method. Always try to split them up to multiple methods (easy to write test too)
Follow the framework's best practices, don't reinvent the wheel.
(to be added more)

Conclusion

Write good code, save lives too.

Cheers!

The art of writing highly readable code

Comments

Journeys

Write unit tests, save time & lifes

More from this blog

Fetch and compute first, write later

Mark as default - the optimal way

Almost 2026, but I still choose WordPress for CMS

Laravel Excel: How to append rows to an existing Excel file

Laravel Herd PRO reviews

Follow General Approaches

Conventions

Naming matters

Variables

Methods

Types

Truthy-first

Stylin'

Conclusion

Command Palette

Comments

Journeys

Write unit tests, save time & lifes

More from this blog

Follow General Approaches

Conventions

Naming matters

Variables

Methods

Types

Truthy-first

Stylin'

Conclusion