Stage 5·Software Craftsmanship

Clean Code Principles

Naming, small functions, comments, and formatting - with before/after refactors.

18 min readIntermediate

On this page

Working code isn't enough. Clean code is code that other humans (including future you) can read, understand, and change safely. Since developers spend far more time reading code than writing it, clarity is a superpower.

Code is read more than it's written

Code is a letter to your future self

You'll revisit code months later with zero memory of what you were thinking. Clean code is a well-written letter: clear, organized, considerate of the reader. Messy code is scribbled shorthand that even its author can't decode later. Write for the person who maintains it - usually you.

Meaningful names

Names are the single biggest lever for readability. A good name makes a comment unnecessary.

// Unclear
int d;                      // elapsed time in days?
List<int[]> list;

// Clear - the name IS the documentation
int elapsedDays;
List<int[]> gameBoardCells;

Rules of thumb: use intention-revealing names, avoid cryptic abbreviations, and make names pronounceable and searchable. Booleans read as questions: isReady, hasPermission.

Small, focused functions

A function should do one thing and do it well. If you need "and" to describe it, split it.

// Doing too much
void processOrder(Order o) {
    // validate... calculate tax... charge card... send email... update db...
}

// One responsibility each
void processOrder(Order o) {
    validate(o);
    double total = calculateTotal(o);
    charge(o.customer(), total);
    notify(o.customer());
}

Small functions read like prose

When each function does one clear thing with a good name, the calling code reads almost like a sentence: validate, calculate total, charge, notify. Anyone can follow the story without diving into details.

Comment why, not what

Good code explains what it does through names and structure. Save comments for why - the reasoning a reader can't infer.

// BAD: restates the obvious
i++;   // increment i

// GOOD: explains a non-obvious decision
// Retry three times because the payment gateway occasionally drops the first request.
retry(3, () -> gateway.charge(amount));

Beware stale comments

A comment that describes what the code does becomes a lie the moment the code changes and the comment doesn't. The best comment is often a better name or a clearer structure that needs no comment at all.

Consistent formatting

Consistent indentation, spacing, and ordering reduce mental load. Let your IDE and a formatter handle it automatically so the whole team's code looks the same. You stop seeing formatting and start seeing logic.

Before and after

// Before: cryptic and cramped
public boolean chk(int x){if(x>18){return true;}else{return false;}}

// After: clear and honest
public boolean isAdult(int age) {
    return age >= 18;
}

Same behavior, dramatically clearer intent.

The Boy Scout Rule

Leave the code a little cleaner than you found it.

You don't need a giant refactor. Rename one unclear variable, extract one messy block, delete one dead line each time you touch a file. Small improvements compound into a healthy codebase.

Quick check

What should a code comment ideally explain?

Key takeaways

Code is read far more than written - optimize for the reader (often future you).
Use intention-revealing names; a good name replaces a comment.
Keep functions small and focused on one thing; the calling code should read like prose.
Comment WHY, not WHAT; beware comments that go stale.
Keep formatting consistent (use a formatter) and follow the Boy Scout Rule: leave code cleaner than you found it.

Clean functions are a start. Next, we scale these ideas up to class design with the SOLID principles.