Blog #40: Don't try to be smart – Write code for humans, not for machines

1. The Context

I was vacationing in Da Lat. The cool air coming into the room felt wonderful. Suddenly, my phone buzzed incessantly. A message in the team chat: "Ivan, the data filter function on the search page is glitching in a special case, and we just can't understand what you wrote to fix it."

I opened my laptop and looked at the function I had written six months ago with all the pride in the world. It was a snippet using "bitwise operators," combined with "reduce" and a mess of "nested ternary operators." At the time of writing, I thought I was... cool. I had used a single line of code to replace about 20 lines of simple code. I thought it was the pinnacle of programming.

But standing in the cool Da Lat air, looking at that very line, it took me 10 minutes to remember how I had "performed" that magic. If the author found it hard to understand, how could I blame the Juniors in the team for being stuck?

2. Foundational Knowledge

There is a classic saying in the industry: "Code is read more often than it is written". You only write code for one hour, but it will be read, edited, and maintained by dozens of others over thousands of hours after that.

"Cleverness" in programming often goes against "Clarity." Clever code is code that utilizes language tricks to make it as short as possible. Clear code is code that even a beginner can guess what it's doing without looking up too much documentation.

3. The Specific Problem

The system needed to filter a product list based on complex user permissions. Instead of writing explicit if/else statements, I performed a "code dance" as follows:

// The "clever" code that stuck the whole team
const filtered = data.reduce((acc, item) => (checkBitmask(item.perm) & user.role_mask) ? [...acc, item] : acc, []);

// And this is why it broke when the logic changed slightly
// A Junior tried to fix it and the result was a memory leak or completely wrong logic.

Juniors often have a tendency to COPY these snippets because they look "Senior." This is the seed of failure in large-scale codebase management.

4. How I Handled It

I had to swallow my ego. I sent back a new piece of code to the team. It was 25 lines long. It used a classic for...of loop, explicit if statements, and had extremely specific intermediate variables like hasPermission, isAuthorized.

I used console.assert to note my assumptions right in the code. Instead of bitwise, I used normal string arrays because they're much easier for humans to read, even if a machine processed them a few microseconds slower.

5. Trade-offs

Writing "for Juniors" has its drawbacks:

• Length: Longer code, more scrolling time.
• Aesthetics: It doesn't look "pro"; it looks like beginner code.
• Performance: Sometimes theoretically slower than deep optimization tips.

Comparison:

• The "high-level" way: Short, fast execution, but extremely high maintenance cost.
• The "for humans" way: Long, easy to understand, almost immediate maintenance.

In an Agency or Product environment with constant pressure to change, maintenance time is ten thousand times more important than the "class" of the code snippet.

6. Lesson Learned

I now understand more clearly: The best code is code you can explain to a non-programmer in just 1 minute.

• Advice: Never write code to prove how good you are. Write code to prove you are a considerate colleague.
• KISS Principle: Keep It Simple, Stupid. Simplicity is the ultimate sophistication.
• Self-reflection: Am I patronizing Juniors by writing overly simple code? No, I am respecting their time and my own time in the future.

A Senior isn't someone who knows the hardest functions. A Senior is someone who knows when to use the easiest functions so the whole team can progress together.

---

Notes on the day I learned to write normal lines of code.