The art of writing highly readable code

The art of writing highly readable code


3 min read

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


  • KISS - "Keep it simple, stupid" "Keep it short, simple"

  • DRY - Don't repeat yourself


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,...


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.


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

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


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


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


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)


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.


  • 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)


Write good code, save lives too.