# Uncle Bob > Clean Code, SOLID, and Clean Architecture principles for code review, refactoring, module design, naming, coupling/cohesion, dependency direction, and responsibility boundaries. Use when the user mentions Uncle Bob, SOLID, clean architecture, clean code, code smells, dependency inversion, single responsibility, or asks to improve code structure. - Skill: `whyzsm/uncle-bob` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add whyzsm/uncle-bob` - Raw SKILL.md: https://api.skillmd.com/api/skills/whyzsm/uncle-bob/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: whyzsm (https://skillmd.com/u/whyzsm) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/whyzsm/uncle-bob --- # 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](references/solid.md). - **S — Single Responsibility**: A class has one reason to change. One actor, one responsibility. - **O — Open/Closed**: Open for extension, closed for modification. Use polymorphism, not conditionals. - **L — Liskov Substitution**: Subtypes must be substitutable for their base types without breaking behavior. - **I — Interface Segregation**: Many specific interfaces beat one general-purpose interface. Clients should not depend on methods they don't use. - **D — Dependency Inversion**: Depend on abstractions, not concretions. High-level modules must not depend on low-level modules. ## Clean Architecture For the full architecture guide, see [references/clean-architecture.md](references/clean-architecture.md). ### The Dependency Rule Source code dependencies must point **inward** — toward higher-level policies. ``` Frameworks & Drivers → Interface Adapters → Use Cases → Entities (outer) (inner) ``` - **Entities**: enterprise business rules, pure domain objects. - **Use Cases**: application-specific business rules (orchestrate entities). - **Interface Adapters**: convert between use case format and external format (controllers, presenters, gateways). - **Frameworks & Drivers**: the outermost layer (DB, web framework, UI). Details. Replaceable. ### Key Rules - Nothing in an inner circle knows about anything in an outer circle. - Data crossing boundaries is simple DTOs or value objects — never framework-specific types. - The database is a detail. The web is a detail. Frameworks are details. ## Component Principles - **Common Closure Principle (CCP)**: classes that change together belong together. - **Common Reuse Principle (CRP)**: don't force users to depend on things they don't use. - **Stable Dependencies Principle**: depend in the direction of stability. - **Stable Abstractions Principle**: stable components should be abstract. ## Code Smells (Red Flags) - Rigidity: small change causes cascade of changes elsewhere. - Fragility: change in one place breaks unrelated code. - Immobility: can't reuse a module without dragging its dependencies. - Needless complexity: speculative generality, premature abstraction. - Needless repetition: copy-paste code (DRY violation). - Opacity: code is hard to understand. - Long functions, large classes, long parameter lists, boolean flags, switch/case on type. ## Testing (TDD) - **Three Laws of TDD**: (1) Write a failing test first. (2) Write only enough test to fail. (3) Write only enough production code to pass. - Tests are first-class code. Keep them clean, readable, fast. - One assert per test (guideline, not dogma). One concept per test. - F.I.R.S.T.: Fast, Independent, Repeatable, Self-validating, Timely. - Test boundaries, not implementations. Test behavior, not methods. ## Applying These Principles When reviewing or writing code, check in this order: 1. **Readability**: Can someone understand this in 30 seconds? 2. **Naming**: Do names reveal intent? 3. **Function size**: Can anything be extracted? 4. **Single Responsibility**: Does each unit have one reason to change? 5. **Dependencies**: Do they point toward stability/abstraction? 6. **Coupling**: Is anything unnecessarily coupled? 7. **Error handling**: Is it clean and consistent? 8. **Tests**: Are they present, clean, and testing behavior?