Clean Code & Best Practices: Naming, Functions, DRY & KISS

Q: What's the right balance with DRY — can you over-apply it?

Yes. DRY is about removing duplication of knowledge — the same logic or rule expressed in multiple places, so a change must be made everywhere. It's valuable because it prevents inconsistency. But applied mechanically to code that merely looks similar (yet represents different concepts that may evolve separately), DRY creates tangled, over-coupled abstractions that are harder to change than the duplication was. The rule of thumb: don't abstract on the first repetition; wait until you're confident the cases are truly the same thing. Some duplication is cheaper than the wrong abstraction.

Clean Code & Best Practices

Clean code is code written to be read and changed by humans, not just executed by machines. Since software is read far more often than it's written — and most of a codebase's life is maintenance — readability is not a nicety; it's the primary determinant of how fast and safely a team can move. The same logic can be a clear, obvious function or an inscrutable tangle, and the difference compounds over every future change.

The good news: clean code follows a small set of learnable principles — good names, small focused functions, comments that explain why, and timeless heuristics like DRY, KISS, and YAGNI. None require genius; they require care and the discipline to value the next reader (often your future self) over a few saved keystrokes now.

TL;DR

Code is read far more than written — optimize for the reader.
Meaningful names and small, focused functions do most of the work.
Comments should explain why, not restate the what.
Apply DRY, KISS, YAGNI — but don't over-abstract.

Quick Example

A good name turns a comment into self-documenting code:

Meaningful Names

Names are the cheapest, highest-impact lever in readable code:

Reveal intent — elapsed_seconds, not t or x.
Avoid abbreviations and single letters (except tiny loop indices).
Be consistent — same concept, same word everywhere.
Functions are verbs (calculate_total), variables are nouns (total_price), booleans read as questions (is_active, has_permission).

💡 If a variable needs a comment to explain what it holds, it usually needs a better name instead.

Small, Focused Functions

Do one thing — a function should have a single, clear responsibility (Single Responsibility).
Keep them short — easier to read, test, and reuse.
Few parameters — many arguments signal the function does too much.
Avoid deep nesting — early returns and guard clauses flatten logic.

Comments That Earn Their Place

Good comments explain why, not what — the code already says what:

The best "comment" is often clearer code (a well-named function or variable) that needs no comment at all. Comments also drift out of date — code that documents itself can't lie.

Timeless Principles

DRY (Don't Repeat Yourself) — extract repeated logic into one place, so a change happens once. But don't over-apply it to coincidentally-similar code.
KISS (Keep It Simple) — prefer the simplest solution that works; complexity is a cost.
YAGNI (You Aren't Gonna Need It) — don't build for hypothetical future needs; solve today's problem.
Boy Scout Rule — leave code a little cleaner than you found it.

See SOLID Principles and Design Patterns for design-level practices, and Code Review/Code Quality for enforcing them.

Best Practices

Name things well — it's the highest-leverage readability investment.
Keep functions small and single-purpose.
**Comment the why, not the what**; prefer self-documenting code.
Apply DRY/KISS/YAGNI with judgment — don't over-abstract or over-engineer.
Refactor continuously — clean as you go, guarded by tests.

Common Mistakes

Cryptic names

Over-engineering for imaginary futures (violating YAGNI)

FAQ

Why does readability matter more than cleverness?

Because code is read far more often than written, and most of its life is spent being maintained, debugged, and extended — usually by people who aren't its author (including your future self). Clever, compact code that's hard to follow slows every future change and hides bugs; clear code that's "obvious" lets the team move fast and safely. The machine doesn't care how elegant your one-liner is, but the next human absolutely does. Optimize for the reader; the cleverness that matters is making complex things simple, not making simple things clever.

Should code have comments, or should it be self-documenting?

Both, in the right proportions. Aim for code that's self-documenting through good names and structure — so most of what it does is obvious without comments, which can't drift out of sync with the code. Reserve comments for the things code can't express: why a non-obvious decision was made, a workaround for an external quirk, or important context and caveats. A comment that just restates the code ("increment i") is noise; a comment explaining a subtle reason is gold. If you're commenting what, consider whether a clearer name or function would serve better.

What's the right balance with DRY — can you over-apply it?

Yes. DRY is about removing duplication of knowledge — the same logic or rule expressed in multiple places, so a change must be made everywhere. It's valuable because it prevents inconsistency. But applied mechanically to code that merely looks similar (yet represents different concepts that may evolve separately), DRY creates tangled, over-coupled abstractions that are harder to change than the duplication was. The rule of thumb: don't abstract on the first repetition; wait until you're confident the cases are truly the same thing. Some duplication is cheaper than the wrong abstraction.

How do I start writing cleaner code today?

Begin with the highest-leverage, lowest-effort habits: name things meaningfully (intent-revealing variables and functions), keep functions small and focused on one thing, and delete comments that restate the obvious while adding comments that explain non-obvious whys. Apply the Boy Scout Rule — leave each file a little cleaner than you found it — and lean on automated linters and formatters to handle style mechanically. You don't need a big rewrite; clean code is built through small, consistent improvements, guarded by tests so refactoring stays safe.