Clean Code & Refactoring

An object hides its data and exposes behaviour - you tell it to do something. A data structure exposes its data and has almost no behaviour - other code reads its fields and does the work.

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.

Always leave code a little better than you found it. Whenever you touch a file, make one small safe improvement — a clearer name, a deleted unused line, an extracted helper — so quality slowly rises instead of decaying.

Feathers defines legacy code as code without tests, regardless of its age or quality. The dilemma: to change code safely you want tests first, but to make the code testable you usually have to change it first.

Refactoring changes how code is structured, never what it does. Callers see the same observable results before and after. Adding a feature, fixing a bug, or changing output is not refactoring — it is a behavior change, done separately.

Take a chunk of code inside a function, move it into a new function whose name says what it does, and call that new function from the original spot. Behaviour stays identical; only the structure changes.

Red: write one small failing test for behavior you want. Green: write the simplest code that makes it pass. Refactor: clean up the code and the test while all tests stay passing. Then repeat with the next small behavior.