Tag: Clean Code

When I tell people I am a software engineer, they picture me typing furiously in a dark room, green text raining down the screen, hacking into something important. The reality is less cinematic. Most days I am staring at a function, holding a coffee that went cold an hour ago, whispering “but why would it do that?”

Software engineering is not mostly about typing. It is about thinking, reading, communicating and making trade-offs, with a little typing sprinkled on top. After more than ten years of building things for the web, from WordPress plugins to real-time 3D configurators, here is what I wish someone had told me on day one.

Programming vs. software engineering

Programming is making the computer do something. Software engineering is making the computer do something for years, while other people change it, the requirements change, the framework releases a new major version and someone in marketing asks if it can “just also do this one small thing”.

A good rule of thumb: programming is what you do alone; engineering is what you do with time and other people. The moment your code has to survive a colleague, a deadline or next year’s version of you, you are doing engineering.

You read code far more than you write it

Every line you write will be read many more times than it was written: by reviewers, by teammates fixing bugs at 6 p.m. on a Friday, and by future you, who will have no memory of writing it and will be personally offended by it.

So optimise for the reader:

• Name things like you mean it. data2, tempFinal and handleStuff are cries for help. unpaidInvoices and retryWithBackoff are documentation.
• Keep functions small enough to fit in your head. If you need to scroll to understand it, your teammates need a map.
• Comment the “why”, not the “what”. The code already says what it does. Tell me why it does it in this weird way, so I don’t “fix” it and break production.

// Bad: tells me what I can already read.
// Add 1 to retries
retries += 1;

// Good: tells me what the code can't.
// The payment provider rate-limits bursts, so we back off
// instead of retrying immediately (see incident 2024-11).
await sleep(2 ** retries * 250);

Simple beats clever (every single time)

Clever code feels amazing to write. It is a little poem only you understand. Unfortunately, it is also a little trap only you can get out of. The best engineers I have worked with write code that looks almost boring. That is the point. Boring code is easy to read, easy to test and easy to delete.

Before you add an abstraction, ask: “Do I have three real cases for this, or am I building a cathedral for one tent?” Duplicating two small things is often cheaper than inventing the wrong abstraction and living with it for two years.

Bugs get more expensive the longer they live

A misunderstanding caught while sketching the solution costs a conversation. The same misunderstanding caught in production costs a hotfix, a postmortem, an apology email and possibly your weekend.

That is why engineering habits that feel slow are actually fast:

• Ask questions before you code. Five minutes of “what should happen when the list is empty?” saves five hours later.
• Write tests for the scary parts. Not everything needs a test, but money, permissions and anything with dates absolutely does. Dates are cursed. Respect the curse.
• Review code like a teammate, not a judge. The goal is a better product, not a scoreboard of who found the most typos.

Every decision is a trade-off

There is no “best” framework, database or architecture. There is only “best for this team, this problem and this deadline”. Junior engineers ask “what is the right answer?” Senior engineers answer “it depends”, and then, crucially, explain what it depends on.

When you make a decision, write down:

1. The problem you were solving.
2. The options you considered.
3. Why you picked this one, and what you gave up.

Three short paragraphs. Future you will send present you a thank-you card.

Communication is part of the job

I used to think the “soft” skills were optional extras. Then I watched a technically perfect feature fail because nobody explained how it worked, and a slightly messy one succeed because the developer kept everyone in the loop. Writing clear pull request descriptions, giving honest estimates and saying “I’m stuck” early are engineering skills. They just don’t compile.

Ship, learn, repeat

Perfect software does not exist. Software that is in users’ hands, teaching you something, does. Ship small pieces, measure what happens, improve. A good engineer is not someone who never makes mistakes; it is someone who makes small mistakes quickly and big mistakes rarely.

The short version

• Write for the reader, especially future you.
• Choose boring, simple solutions until you can’t.
• Catch bugs early: questions, tests and kind reviews.
• Every choice is a trade-off. Write it down.
• Talk to humans. They are part of the system too.

And reheat your coffee. Cold coffee has never fixed a bug, although I have tested this hypothesis extensively.