The gap between code that runs and software that works

The demo lied to you — politely

Most early wins in software look the same: a screen appears, an API returns 200, the test is green. You feel competent. You should. Making something run is a real skill.

Then the questions change.

Why this table shape? What happens when two users edit at once? Who owns the failure at 2 a.m.? What do we delete when the requirement was wrong?

Tutorials rarely ask those questions. Interviews and production do. The gap between code that runs and software that works is not more syntax. It is judgment under constraints.

What “works” actually means

Software that works is not the same as software that executes.

It means:

• The behavior matches a real need — not a tutorial checklist
• Failures are visible and recoverable
• Another engineer can change it without archaeology
• The cost of the design is acceptable for the next few years — not just the next demo

A script that prints “Hello” works as a demo. A payment path that double-charges under retries does not “work,” even if every unit test is green.

Where the gap shows up

Interviews

You can recite React hooks and still freeze when asked: Walk me through how you would design this. The interviewer is not testing memorization. They are testing whether you can hold trade-offs in your head.

First jobs

Tickets say “add a field.” Production says “that field is read by three jobs, two reports, and a partner feed.” The gap is context. Tutorials give you isolated problems. Companies give you systems.

Side projects that never leave the laptop

They run. They impress friends. They never meet messy users, messy data, or messy time. Leaving the laptop is where “works” gets defined.

How to shrink the gap (without another course binge)

1. Explain a decision out loud. Pick something you built. Say what you discarded and why. If you cannot, you do not understand it yet.
2. Read one failure mode per feature. Ask: what happens when the network is slow, the user retries, the data is empty, the dependency is down?
3. Maintain something for a month. Ownership teaches more than a new framework.
4. Write the trade-off. One paragraph: what we gained, what we owe later. That habit is engineering.

You do not need permission to practice judgment. You need problems that have consequences — even small ones.

What we will keep writing about

At The Code Craftsmen we care about this gap on purpose. Frameworks change. The need to reason about systems does not.

Upcoming pieces will dig into concrete systems — including architecture migrations and rule engines under real volume. This essay is the door: name the gap before you try to cross it.