Uncle Bob — Clean Code & Architecture Principles

Apply these principles when writing, reviewing, or refactoring code. They are not rules to follow blindly — use judgment, but default to clean.

The Boy Scout Rule

Leave the code cleaner than you found it. Every commit should improve the codebase, even if slightly.

Clean Code Fundamentals

Naming

• Names reveal intent. If a name requires a comment, the name is wrong.
• Use pronounceable, searchable names. Avoid abbreviations, single letters (except loop counters), and prefixes.
• Classes/types: noun or noun phrase (AccountManager, OrderRepository).
• Functions/methods: verb or verb phrase (calculateTotal, fetchUser, isValid).
• Booleans: read as a question (isActive, hasPermission, canExecute).
• Avoid mental mapping. r is not a URL. Say url.

Functions

• Small. Then smaller. A function does one thing.
• Ideally 0-2 arguments. 3+ is a smell — extract an options object or rethink the design.
• No side effects. A function named checkPassword must not also initialize a session.
• Command-Query Separation: a function either does something (command) or answers something (query), never both.
• Don't Repeat Yourself (DRY) — but don't abstract prematurely. Three instances of duplication is the threshold.
• Extract till you drop: if you can extract a meaningful sub-function, do it.

Comments

• Good code is self-documenting. Comments compensate for failure to express in code.
• Legal, informative, clarifying intent, warning of consequences, and TODO comments are acceptable.
• Delete commented-out code. Version control remembers.
• Never write comments that restate what the code does (// increment i before i++).

Formatting

• Vertical: newspaper metaphor — high-level summary at top, details below.
• Related functions stay close. Caller above callee.
• Horizontal: avoid scrolling. Keep lines short.
• Consistent formatting across the team trumps personal preference.

Error Handling

• Prefer exceptions/Result types over error codes.
• Don't return null. Don't pass null.
• Write try-catch at the top level of a function, not scattered throughout.
• Error handling is one thing — a function that handles errors should do little else.
• Define exception classes in terms of the caller's needs, not the thrower's implementation.

Objects vs. Data Structures

• Objects hide data, expose behavior. Data structures expose data, have no behavior.
• Don't mix them. A class with public fields AND business methods is the worst of both worlds.
• Law of Demeter: a method should only call methods on its own object, its parameters, objects it creates, or its direct dependencies. No a.getB().getC().doThing().

SOLID Principles

For detailed explanations and examples, see references/solid.md.