Any fool can write code that a computer can understand. Good programmers write code that humans can understand

Martin Fowler

While implementing cute solutions to problems and linting the hell out of our code-bases, we lost our way.

Whenever I look at a code-base these days written in React, or JavaScript, or even C#, I find it extremely difficult to follow what the developer is trying to convey.

I end up opening 10 to 20 files in my IDE to understand a simple workflow. There are just too many “hidden” areas that you need to know about in order to understand a piece of code.

Speaking strictly of front-end code, we have unanimously accepted event-driven workflows. But events were never human-friendly, were they? Over-reliance on knowing all event-emitters and subscribers kills all rhythm when you’re trying to read someone’s code.

A simple example of convoluted workflows can be visualized as follows:

Let’s say you want to write a program that to accept product orders. In a very simplified workflow, the program should create an order by executing the following steps:

1. Accept a product to create order
2. Check inventory for availability
3. Write to the Orders queue or table
4. Give user acknowledgement of the order

For me to understand this whole workflow, I should have to open a OrderProcessor file and see four methods that are doing exactly these things:

BeginOrderProcessing(productId);

CheckInventory(productId);

CreateOrder(productId, …otherInfo);

NotifyOrderSuccessful();

I don’t need to open any other file to understand the workflow on a very high level. If I want to bother myself with the details of any of these processes I’ll just go to the implementation.

But almost always when I look at some code, I find that someone put **CreateOrder **in **CheckInventory **and **NotifyOrderSuccessful **in **CreateOrder **leaving me oblivious to the actual workflow. It’s not like the intended functionality won’t work. It will, as there’s nothing wrong with the instructions to a **computer **here,but communicating intent to the **human **was sacrificed along the way.

#faisal-rashid #code #coding-problems #martin-fowler #code-for-humans