Writing Clean Code

Cyclomatic complexity counts the independent execution paths through code, which estimates how many tests you need. Cognitive complexity estimates how hard code is for a human to read: it penalises nesting and ignores structures people find easy.

A guard clause handles an invalid or special case immediately and returns, instead of wrapping the real work in an if. That flattens nesting, so the reader stops carrying conditions in their head and the main path stays at the left margin.

The code already shows what it does; a reader can see that. It cannot show the reason, constraint, or bug that forced this approach. "Why" comments add information; "what" comments repeat it and can go stale.

Error codes force every caller to check the returned value right at the call site, mixing error checks into the happy path. Exceptions move failure handling out of the main flow, and they cannot be silently ignored, so the code reads cleaner and is safer.

Returning null forces every caller to add a null check; one forgotten check crashes at runtime, far from the cause. Instead return an empty collection, a default "do-nothing" object (Null Object), or an explicit optional type. Never pass null as an argument.

Read a source file like a newspaper article: the name at the top tells you what it is, the first code gives the high-level story, and details get lower-level as you scroll down. So put high-level functions first and their helpers below.

It means the function performs a single, clearly nameable job. Signs of violation: you can extract a meaningful chunk into another function that isn't just restating the original, the name needs "and"/"or", or the body mixes unrelated steps.

A boolean parameter means the function does two things — one per branch — and the call site save(user, true) is unreadable. Fix by splitting into two clearly named functions. Prefer 0-2 parameters; 3 is suspicious; 4+ usually means a missing object.

An intention-revealing name says what the thing is, why it exists, and how it is used — so no comment is needed. Comments drift out of date silently; a name is re-read every time the code is read.

Classes and modules get noun phrases (things): Invoice, PaymentGateway. Methods get verb phrases (actions): send, calculateTotal. Boolean members read as a true/false statement: isEmpty, hasPermission. Readers then parse code as sentences instead of decoding it.

The Law of Demeter says a method should only talk to its immediate neighbours: itself, its own fields, its parameters, and objects it created. Long chains like that one couple your code to the internal structure of three other classes, so any of them changing breaks you.

Good: legal/licence headers, intent, clarification of code you can't change, warnings of consequences, TODOs, and public API docs. Bad: redundant restatement, journal/changelog entries, commented-out code, noise, banners, attributions. Criterion: does it tell the reader something the code cannot?

Design exception types around how callers will handle failures, not around where they came from. If a caller treats ten library exceptions identically, wrap them in one of your own exception types thrown from a thin adapter, so the calling code has one catch block and no dependency on the library.

A disinformative name implies something untrue — accountList for a set, getUser that also creates one. Noise words add characters but no meaning — Data, Info, the, Object. One word per concept means picking a single verb per operation across the codebase (get, not get/fetch/retrieve).

Do not let a third-party type spread through your codebase. Wrap it behind an interface you own, expressed in your domain's terms, and keep the vendor types inside that wrapper. Learning tests are small tests you write against the library to verify how it actually behaves - and they warn you when a version upgrade changes that behaviour.

It means naming and structuring code so it explains itself: rename vague identifiers, extract a commented block into a well-named function, and put a complex condition into a named variable. It fails for reasons outside the code — external constraints, hazards, and decisions.

Formatting arguments waste review time and have no effect on behavior, so a formatter should decide and CI should check it. To adopt one on an old codebase, reformat everything in one dedicated commit and tell the blame tool to ignore that commit.

Every statement in a function should sit at roughly the same conceptual distance from the domain — don't mix high-level policy with low-level string or byte fiddling. Step-down means each function is followed by the ones it calls, so the file reads top to bottom, general to detailed.

A hybrid is a class that both exposes all its data through getters/setters and carries important business behaviour. It gets the downsides of both styles. Feature envy is code that uses another object's data more than its own; Tell-Don't-Ask fixes it by moving the behaviour to the data.

Each structure that breaks straight-line reading — if, else, loops, catch, switch, jumps — adds one point, plus one more for each level of nesting it sits inside. Shorthand that condenses code (a whole switch, the method declaration itself) adds nothing extra.

It is dead text nothing checks: no compiler, no tests, no refactoring tool touches it, so it silently goes stale. Readers won't delete it because they assume it matters. Version control already stores it — delete it and recover from history if needed.

Write the failing case first — start with a test that expects the exception, then a try/catch/finally skeleton, then fill in the happy path. A function that handles errors should do only that: try is the first statement, and there's nothing after the catch/finally block.

Aligning values into a neat column looks tidy but breaks the moment a name changes, producing large diffs and constant re-alignment. Line limits exist mainly so code fits side-by-side diffs and review windows without horizontal scrolling.

Vertical openness means putting a blank line between separate thoughts so each stands out. Vertical density means keeping tightly-related lines packed together with no blank lines, so they read as one unit.

CQS says a function should either change state (a command, returning nothing) or return a value (a query, changing nothing) — never both. It keeps queries safe to call and read, so if (set(x)) style confusion disappears.

Hungarian notation prefixes a name with its type — strName, iCount, lpszBuffer. Modern languages and IDEs already show types, so the prefix adds noise and becomes a lie the moment the type changes. Name the meaning instead.

Objects make it easy to add new types (write one class; existing code is untouched) but hard to add new operations (every class must change). Plain data plus procedures is the exact opposite. So pick based on which change you expect more often.

Check whether each helper's name lets you skip its body. If you must open all six to understand the original function, the complexity just moved and reading now costs six jumps. Good extraction removes detail; bad extraction only relocates it.

Anything the reader must hold in their head while reading on: long-lived mutable variables, boolean flag parameters, unnamed intermediate conditions, hidden side effects, and jumping between distant files. Fix by naming intermediates, shrinking variable lifetimes, and making each named function a single chunk.