Clean Code

1Naming is design

The naming chapter alone is worth the price of the book. Its opening example: int d; // elapsed time in days. The comment is trying to rescue the name. Martin replaces it with elapsedTimeInDays and states his rule: "if a name requires a comment, then the name does not reveal its intent" (p. 18). It sounds trivial, but the deeper idea is this: if you can't find a clear name for a function, it's often because the function does too many things. The name is a design test in disguise.

2A function does one thing

Short, one level of abstraction, two or three arguments at most. One level of abstraction means the function names its steps without implementing them: shipOrder() calls checkStock(), computeTotal(), printLabel() — it does none of those things itself. Code should read top to bottom like a newspaper article: headline first, details after. It's the principle I apply most in my daily work, and the one I see least in the codebases I inherit.

3A comment is an admission of failure

Martin is radical on this, and the book's actual wording is harsher than its reputation: "Comments are always failures" (p. 54). His example, in code:

// ✗ the deodorant comment: it explains an obscure condition
// the employee has over 5 years of seniority AND is full-time
if (emp.seniority > 5 && emp.fullTime) { ... }

// ✓ extract a method that SAYS the same thing, and can't lie
if (emp.isEligibleForFullBenefits()) { ... }

The comment ages and lies within six months; the well-named method is checked by the compiler and stays true. The only legitimate comments explain the why, not the what:

• a business constraint that code alone can't express;
• a warning of consequences ("don't change this order — the payment processor requires it");
• a deliberate decision that would surprise a future reader.

Everything else ages badly, starts lying within six months, and nobody ever updates it.

4Errors are handled, not hidden

Exceptions instead of return codes, fail fast and loud instead of limping along in a corrupted state. Three rules the book makes non-negotiable:

• never an empty catch — try { ... } catch (e) {} is a future bug with an unknown expiry date;
• never return null — you're creating null-checking work for every caller, and one missed check is enough for a crash;
• never pass null as an argument — the callee can't tell if it's an oversight or an intentional value.

// ✗ the empty catch: the error vanishes, the bug stays (and the payment?)
try { payment.charge(amount) } catch (e) {}

// ✓ log it and let it bubble up: never swallow it silently
try { payment.charge(amount) }
catch (e) { logger.error(e); throw e }

5Don't talk to strangers

The Law of Demeter, and its vivid nickname: the "train wreck". A chain like $order->getCustomer()->getAddress()->getCity() couples your code to the internal structure of three different objects. The day one of them moves, everything breaks. Expose a method that says what you want, not the path to get there.

6Test code is real code

TDD (Test-Driven Development) means writing the test before the code. The chapter states its three laws:

• no production code without a failing test first;
• write just enough test to fail (compilation failure counts);
• write just enough code to make it pass.

A cycle "that is perhaps thirty seconds long" (p. 122), far shorter than most people imagine. And the point that stuck with me: Martin tells of a team that decided test code could stay dirty; the tests rotted, got thrown away, and defects soared. A messy test nobody dares touch eventually gets deleted, and the safety net goes with it.

7SOLID running through it all

Five principles, one acronym. The book doesn't present them as a catalogue; it brings them to life through examples:

• S — Single responsibility: a class has only one reason to change. A UserService that handles both authentication and email sending has two — split them;
• O — Open/closed: open for extension, closed for modification (add behaviour without touching existing code);
• L — Liskov substitution: a subclass must be usable wherever its parent is, without breaking anything;
• I — Interface segregation: better several small interfaces than one large one that forces classes to implement methods they don't need;
• D — Dependency inversion: depend on abstractions, not on concrete implementations.

The most useful one day to day, S, in code: a class should have only one reason to change.

// ✗ S violated: UserService changes if auth changes OR if email changes
class UserService {
  authenticate(login, pwd) { ... }
  sendWelcomeEmail(user) { ... }
}

// ✓ one class = one single reason to change
class Authenticator { authenticate(login, pwd) { ... } }
class Mailer        { sendWelcomeEmail(user) { ... } }

This is exactly the SRP dissected in the Clean Architecture note ("a module answers to one single chain of command"): here auth answers to the security team, email to the marketing team. Two bosses, two classes.

8The boy scout rule

"Leave the campground cleaner than you found it" (p. 14), adapted from Baden-Powell's farewell message to the Scouts. Probably the most famous line in the book, and the most applicable starting tomorrow morning: no big-bang refactoring needed, just a rename here, an extracted function there, every time you pass through a file. Technical debt recedes through small touches, not revolutions.