Write Code Like You’ll Maintain It
Clear code today saves you from confusion tomorrow.
Most of us write code for the moment.
We’re trying to fix a bug. Ship a feature. Hit a deadline.
Maintenance feels like a future problem. But here’s the truth: future you is the one who pays for today’s shortcuts.
I’ve learned this the hard way.
The code isn’t done when it works
Getting something to run is only step one.
You know that feeling when the feature finally works and you think, “Good enough”? That’s usually the point where the real work should start.
Ask yourself:
- Would I understand this in six months?
- Would a new teammate understand this in six minutes?
- Is the naming obvious?
- Is the logic doing one thing or five?
If the answer makes you hesitate, it’s not done.
Working code is not the goal. Clear code is.
Name things like you mean it
Bad names are expensive.
data, value, temp, handleStuff — these are signs you were in a rush.
Naming forces you to think. When you struggle to name something, it usually means the idea isn’t clear yet.
For example:
calculatePrice()
Calculate what price? With tax? With discount? For which user?
A better name might be:
calculateDiscountedPriceWithTax()
Longer? Yes. Clearer? Also yes.
Clarity beats cleverness every time.
Fewer abstractions, not more
Early in my career, I loved abstractions.
Custom hooks for everything. Utility layers. Reusable patterns for cases that only happened once.
It felt smart.
But too many abstractions hide intent. They make simple code harder to follow.
If something is only used in one place, it probably belongs in that place.
Duplication is not always bad. Confusing indirection is worse.
You can always extract later. It’s much harder to simplify over-engineered code.
Comments are not a rescue plan
If your code needs a paragraph to explain it, something is wrong.
This:
// This function loops through the array and checks if the user is active
…should not be necessary.
Your code should already say that.
Comments are useful when they explain why, not what.
For example:
// We intentionally skip caching here because user permissions change often.
That helps future you. It explains context. That’s what comments are for.
Write smaller functions
Large functions hide bugs.
When a function does too much, you stop reasoning about it. You just hope it works.
A simple rule I follow: if I have to scroll a lot to see the whole function, it’s probably doing too much.
Break it into smaller pieces. Each function should do one clear thing.
This makes testing easier. It also makes reading easier.
And reading code is most of the job.
Think about the next person
Code is a form of communication.
You are not writing for the compiler. You are writing for other humans.
Even if you work alone, the “other human” is future you.
Be kind to that person.
- Avoid clever tricks unless they truly simplify.
- Prefer boring solutions.
- Stick to common patterns in your ecosystem.
Boring code is underrated. It is predictable. Predictable code is easy to trust.
Actually, I don’t think clever code is cool anymore. I think understandable code is cool.
Tests are a gift to yourself
Tests are not just for catching bugs.
They document behavior.
When you come back to a piece of code and don’t remember what it’s supposed to do, the tests tell you.
Even a few basic tests help:
- Does it handle empty input?
- Does it handle invalid input?
- Does it return the expected shape?
You don’t need perfect coverage. You need confidence.
That’s enough.
Slow down a little
Rushing feels productive.
But debugging unclear code later is slow. Very slow.
Spending an extra 10 minutes:
- Renaming variables
- Removing dead code
- Simplifying a condition
- Splitting a function
…usually saves hours down the line.
It’s not glamorous. But it works.
The real goal
When I look back at old projects, I rarely think, “Wow, that was fast.”
I think:
- Why is this so hard to follow?
- Why did I make this so complicated?
- What was I even thinking here?
Good code ages well.
It reads simply. It feels obvious. It doesn’t try to impress anyone.
That’s the kind of code I try to write now.
Not perfect. Just clear.
And honestly, that’s enough.
