Readable code for vibecoders: names, DRY, KISS

What readable code means in plain terms

Picture two fridges. In the first one, everything is labeled: “sauces,” “breakfast,” “do not touch - this is for the party.” Open it and you find what you need in three seconds. The second one has twenty identical containers without a single label. To find the yogurt, you open each one and sniff it. Sometimes you find something you really should not have sniffed.

Code can be exactly like this. Readable code is the labeled fridge. Unreadable code is those twenty containers: “soup number one,” “soup number two,” x, y, flag. And here’s the annoying part: unreadable code tortures both you and your AI agent equally.

Why a vibecoder needs readable code

You’re a vibecoder. You don’t write code by hand - you order it from the agent. And that’s exactly why readability matters twice as much:

• want to change something - you (or the agent) will find the right spot in seconds, not half an hour;
• reading readable code, the agent spends fewer tokens and makes fewer mistakes - it doesn’t have to guess what kind of beast this q is;
• fewer bugs: half of all breakage is born from “oops, I thought this variable was about something else”;
• the project doesn’t turn into a swamp a month later, when you yourself forget what you even wrote.

Readable code is a gift to your future self. And future-you will absolutely forget what tmp2 is and why this 86400 is here. (Spoiler: it’s the number of seconds in a day. But you’ll only learn that after an hour of googling.)

Four clean-code rules Claude follows

Good agents stick to the basic rules of clean code by default. It pays to know them by sight - so you can ask for exactly this and instantly spot when the agent cut corners.

1. Descriptive names for variables and functions

A variable or function name should explain what’s inside. Without a single comment.

2. DRY - don’t repeat the same code

DRY DRY (Don't Repeat Yourself) is the principle that the same piece of logic lives in one place. Need it in three places - pull it into a shared function and call that. is about copy-paste. Copied the same chunk three times? Congratulations: you now own three places that have to be edited in sync. Forget one - you’ve got a bug. And of course it’ll go off at the worst possible moment.

The fix is surprisingly simple. Pull the shared chunk into one function and call it from everywhere. Change it in one place - it changes everywhere.

3. KISS - keep it simple, don’t overcomplicate

KISS KISS (Keep It Simple, Stupid) is the principle of taking the simplest solution that works. Don't overcomplicate for a future that may never arrive. is about the temptation to “make it slick and future-proof.” Don’t. The simplest solution that works almost always beats the clever one. Readable code that works always wins over tricky code you have to decode like a puzzle.

Right next door lives its kindred spirit, YAGNI YAGNI (You Aren't Gonna Need It) - don't write code for a hypothetical future. If you need it, you'll add it then. : don’t ask the agent to build features that “might come in handy.” If they do, you’ll add them - it’s five minutes. But dragging extra code around the whole time is expensive and tedious.

4. Magic numbers: replace them with named constants

A magic number A magic number is a number sitting right in the code with no explanation, like 3 or 86400. It's unclear what it means or whether you can change it. The fix: give the number a name - a constant. is a bare number sitting in the middle of the code. You see retryCount > 3 - but why exactly 3? And what blows up if you set it to 5? Give the number a name: MAX_RETRIES = 3. The meaning is right there, and now you change it in a single line.

A real-life example: an online store cart

You asked the agent: “build a cart for an online store.” A week later you ask: “add a 10% discount for orders over $5,000.” And here the pain begins:

1. The agent wrote the total calculation in three places - on the product page, in the cart, and at checkout. Pure copy-paste. The discount has to go in three times, and in one of them it of course forgets.
2. The bare number 5000 is sticking out of the code with no name. The agent isn’t sure: is it the discount threshold, a shipping limit, or something else?
3. Variables are named a, sum2, tmp. The agent burns tokens trying to figure out what’s what - and still gets confused.

Now watch how to ask the right way from the start - so none of this pain ever happens:

Build a cart for an online store. Write readable code following simple rules:


Give variables and functions descriptive names. Not x and tmp, but cartTotal, applyDiscount, isEligibleForDiscount. Functions - a verb plus what it’s about.


Don’t duplicate logic. The final total calculation should live in one function that’s called from everywhere, not copied across pages.


Don’t hardcode bare numbers. Pull the discount threshold and percentage into named constants at the top, like DISCOUNT_THRESHOLD and DISCOUNT_PERCENT, so they’re easy to change in one place.


Keep it as simple as possible. No “future-proofing” I didn’t ask for.

After the code, briefly explain where each constant is and where the total calculation lives.

Common vibecoder mistakes with code

• Settling for names like x, tmp, data2. Spot these in the agent’s code - ask it to give them proper, descriptive names. It’s free and saves hours.
• Tolerating copy-paste. The same chunk in three places - ask to pull it into a shared function. Otherwise the edits drift apart, and something is bound to fall off.
• Leaving bare numbers. Any “magic” number - ask to turn it into a named constant with a clear name.
• Allowing “future-proofing.” Extra features that “might come in handy” are extra code you have to read and carry around. Ask for the simplest thing that solves the task.
• Thinking readability is for programmers. It’s the opposite: the more readable the code, the less often you, the vibecoder, will have to dig into the technical weeds when something needs fixing.