How to Write Clean and Maintainable Code: A Practical Guide

There's a specific kind of dread that hits you when you open a file you wrote eight months ago and can't figure out what it does.

I've been there. I once spent almost four hours on a Tuesday morning trying to trace why a checkout function was returning the wrong total, only to discover it was a variable named data2 holding a user object that everyone, including me, had assumed was an invoice array. Buried in 340 lines of nested conditionals. I wrote that code. I was the only person who had ever touched it. And I still couldn't read it.

That moment is why I care about writing clean, maintainable code. Not because a style guide told me to. Because the person you're really writing for is you in six months, half-awake, on your third coffee, wondering why the build is red.

If you want to know how to write clean and maintainable code, most advice you'll find is a list of platitudes. This is the version I actually use, with the numbers and the trade-offs.

What clean and maintainable code actually means

Everyone says "clean code is readable." Nobody tells you how to measure readability, so the phrase becomes decoration.

Here's the working definition I use with my team. Code is clean if a new developer can make a safe change in under 30 minutes without asking anyone a question. That's it. Everything else is a proxy.

The three numbers I actually track

Cyclomatic complexity tells you how many independent paths run through a function. Anything above 10 in a business-logic file is a warning; above 20 is a rewrite candidate. Duplication percentage from a static analyzer tells you how much copy-paste debt you're carrying. And test coverage on the modules that change most often — the hot spots, not the whole repo.

I'll be blunt: I chased 100% coverage once. It cost my team about six weeks of velocity and produced a graveyard of brittle tests that broke on every refactor. We dropped to around 70% global coverage with 95% on the critical paths and shipped faster. That trade is worth considering on your side too.

Readability beats cleverness every time

I have a rule I'll defend to the end: if a piece of code makes you feel clever, delete it and write the boring version. The clever version is a time bomb that detonates in someone else's pull request.

Names and small functions do 80% of the work

Sound familiar? You open a file and see handleStuff, tmp, x, and processData2. Nothing about the shape of the module helps you.

Naming rules that hold up under pressure

• A function name should state what it returns: getActiveUsers, not fetchStuff.
• Booleans read as questions: isExpired, hasPermission, canRetry.
• Never encode type in the name. userList ages badly the day you swap a list for a stream.
• Avoid abbreviations nobody agrees on. usr and acct save four characters and cost two minutes every time someone pauses to decode them.

The rule of one thing per function

A function should do one thing. If you can't describe what it does without the word "and," split it. I keep a practical ceiling of 20 lines per function, and a hard rule that no function exceeds one level of nesting beyond its own body. That single rule eliminated most of the bugs I was writing at the time.

Automate the boring parts or you'll never do them

Manual discipline fails. Every team I've seen that relies on "everyone remembers to format their code" drifts within three sprints.

Tooling I install on day one

Prettier or Black for formatting, ESLint or Ruff for linting, and a static analyzer like SonarQube or CodeQL for the deeper smells. Wire all three into CI so a pull request with a complexity spike or a duplicated block fails the build. The linter is not there to punish juniors; it's there to remove every stylistic argument from code review.

What automation can't fix

It cannot tell you that a function is named badly. It cannot spot a missing abstraction. It cannot feel the friction of a confusing flow. Those require human review, and that's exactly where review time should go.

How the main techniques compare in practice

Practice	Effort to adopt	Payoff window	Biggest failure mode
Naming and function size	Low	Immediate	Reverting under deadline pressure
Automated formatting and linting	Low	Days	Ignoring warnings until they become noise
Test coverage on hot spots	Medium	Weeks	Chasing a number instead of testing behavior
Refactoring legacy modules	High	Months	Turning a refactor into a rewrite
Documentation of decisions	Low	Weeks	Writing a novel nobody reads

Applying this to legacy code without setting it on fire

The advice above is easy on greenfield. Real work happens in codebases that predate you.

On one project, I inherited a 90,000-line service with no tests and a deployment pipeline that took 40 minutes. The temptation was to rewrite. I didn't. I spent the first two weeks just adding characterization tests around the modules we touched most. Then I refactored one file per sprint. Six months later, complexity on those files had dropped by roughly half and deployment was down to about nine minutes.

Two rules I now follow without exception:

1. Never refactor and add a feature in the same pull request. The reviewer can't tell which change broke the behavior.
2. Leave code slightly better than you found it. One rename, one extracted function, one removed duplication. Compounding wins over heroics.

The cost of clean code nobody mentions

There's an uncomfortable truth: clean code has a price. The extra hour you spend extracting a function is an hour not spent shipping the feature. If your startup has three weeks of runway, that calculation changes.

My honest position: optimize for the next person who reads this file, and assume that person is tired. That heuristic covers almost every case without requiring you to win an architecture debate.

What's the last piece of code you wrote that you genuinely couldn't reread without wincing? Go look at it today. You'll learn more in ten minutes than in a week of reading about it.