home / skills / pproenca / dot-skills / clean-code

clean-code skill

safe

This skill helps you write, review, and refactor clean, maintainable code by applying Uncle Bob's naming, structure, and error guidelines.

npx playbooks add skill pproenca/dot-skills --skill clean-code

Review the files below or copy the command above to add this skill to your agents.

Files (52)

SKILL.md

6.9 KB

---
name: clean-code
description: Use when writing, reviewing, or refactoring code for maintainability and readability. Triggers on code reviews, naming discussions, function design, error handling, and test writing. Based on Robert C. Martin's Clean Code handbook with modern corrections.
---

# Robert C. Martin (Uncle Bob) Clean Code Best Practices

Comprehensive software craftsmanship guide based on Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship", updated with modern corrections where the original 2008 advice has been superseded. Contains 48 rules across 10 categories, prioritized by impact to guide code reviews, refactoring decisions, and new development. Examples are primarily in Java but principles are language-agnostic.

## When to Apply

Reference these guidelines when:
- Writing new functions, classes, or modules
- Naming variables, functions, classes, or files
- Reviewing code for maintainability issues
- Refactoring existing code to improve clarity
- Writing or improving unit tests
- Wrapping third-party dependencies

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Meaningful Names | CRITICAL | `name-` |
| 2 | Functions | CRITICAL | `func-` |
| 3 | Comments | HIGH | `cmt-` |
| 4 | Formatting | HIGH | `fmt-` |
| 5 | Error Handling | HIGH | `err-` |
| 6 | Objects and Data Structures | MEDIUM-HIGH | `obj-` |
| 7 | Boundaries | MEDIUM-HIGH | `bound-` |
| 8 | Classes and Systems | MEDIUM-HIGH | `class-` |
| 9 | Unit Tests | MEDIUM | `test-` |
| 10 | Emergence and Simple Design | MEDIUM | `emerge-` |

## Quick Reference

### 1. Meaningful Names (CRITICAL)

- [`name-intention-revealing`](references/name-intention-revealing.md) - Use names that reveal intent
- [`name-avoid-disinformation`](references/name-avoid-disinformation.md) - Avoid misleading names
- [`name-meaningful-distinctions`](references/name-meaningful-distinctions.md) - Make meaningful distinctions
- [`name-pronounceable`](references/name-pronounceable.md) - Use pronounceable names
- [`name-searchable`](references/name-searchable.md) - Use searchable names
- [`name-avoid-encodings`](references/name-avoid-encodings.md) - Avoid encodings in names
- [`name-class-noun`](references/name-class-noun.md) - Use noun phrases for class names
- [`name-method-verb`](references/name-method-verb.md) - Use verb phrases for method names

### 2. Functions (CRITICAL)

- [`func-small`](references/func-small.md) - Keep functions small
- [`func-one-thing`](references/func-one-thing.md) - Functions should do one thing
- [`func-abstraction-level`](references/func-abstraction-level.md) - Maintain one level of abstraction
- [`func-minimize-arguments`](references/func-minimize-arguments.md) - Minimize function arguments
- [`func-no-side-effects`](references/func-no-side-effects.md) - Avoid side effects
- [`func-command-query-separation`](references/func-command-query-separation.md) - Separate commands from queries
- [`func-dry`](references/func-dry.md) - Do not repeat yourself

### 3. Comments (HIGH)

- [`cmt-express-in-code`](references/cmt-express-in-code.md) - Express yourself in code, not comments
- [`cmt-explain-intent`](references/cmt-explain-intent.md) - Use comments to explain intent
- [`cmt-avoid-redundant`](references/cmt-avoid-redundant.md) - Avoid redundant comments
- [`cmt-avoid-commented-out-code`](references/cmt-avoid-commented-out-code.md) - Delete commented-out code
- [`cmt-warning-consequences`](references/cmt-warning-consequences.md) - Use warning comments for consequences

### 4. Formatting (HIGH)

- [`fmt-vertical-formatting`](references/fmt-vertical-formatting.md) - Use vertical formatting for readability
- [`fmt-horizontal-alignment`](references/fmt-horizontal-alignment.md) - Avoid horizontal alignment
- [`fmt-team-rules`](references/fmt-team-rules.md) - Follow team formatting rules
- [`fmt-indentation`](references/fmt-indentation.md) - Respect indentation rules

### 5. Error Handling (HIGH)

- [`err-use-exceptions`](references/err-use-exceptions.md) - Separate error handling from happy path
- [`err-write-try-catch-first`](references/err-write-try-catch-first.md) - Write try-catch-finally first
- [`err-provide-context`](references/err-provide-context.md) - Provide context with exceptions
- [`err-define-by-caller-needs`](references/err-define-by-caller-needs.md) - Define exceptions by caller needs
- [`err-avoid-null`](references/err-avoid-null.md) - Avoid returning and passing null

### 6. Objects and Data Structures (MEDIUM-HIGH)

- [`obj-data-abstraction`](references/obj-data-abstraction.md) - Hide data behind abstractions
- [`obj-data-object-asymmetry`](references/obj-data-object-asymmetry.md) - Understand data/object anti-symmetry
- [`obj-law-of-demeter`](references/obj-law-of-demeter.md) - Follow the Law of Demeter
- [`obj-avoid-hybrids`](references/obj-avoid-hybrids.md) - Avoid hybrid data-object structures
- [`obj-dto`](references/obj-dto.md) - Use DTOs for data transfer

### 7. Boundaries (MEDIUM-HIGH)

- [`bound-wrap-third-party`](references/bound-wrap-third-party.md) - Wrap third-party APIs
- [`bound-learning-tests`](references/bound-learning-tests.md) - Write learning tests for third-party code

### 8. Classes and Systems (MEDIUM-HIGH)

- [`class-small`](references/class-small.md) - Keep classes small
- [`class-cohesion`](references/class-cohesion.md) - Maintain class cohesion
- [`class-organize-for-change`](references/class-organize-for-change.md) - Organize classes for change
- [`class-isolate-from-change`](references/class-isolate-from-change.md) - Isolate classes from change
- [`class-separate-concerns`](references/class-separate-concerns.md) - Separate construction from use

### 9. Unit Tests (MEDIUM)

- [`test-first-law`](references/test-first-law.md) - Follow the three laws of TDD
- [`test-keep-clean`](references/test-keep-clean.md) - Keep tests clean
- [`test-one-assert`](references/test-one-assert.md) - One concept per test
- [`test-first-principles`](references/test-first-principles.md) - Follow FIRST principles
- [`test-build-operate-check`](references/test-build-operate-check.md) - Use Build-Operate-Check pattern

### 10. Emergence and Simple Design (MEDIUM)

- [`emerge-simple-design`](references/emerge-simple-design.md) - Follow the four rules of simple design
- [`emerge-expressiveness`](references/emerge-expressiveness.md) - Maximize expressiveness

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

Overview

This skill guides writing, reviewing, and refactoring TypeScript code for maintainability and readability using Clean Code principles updated for modern practices. It targets naming, function and class design, error handling, testing, and boundaries to reduce cognitive load and technical debt. Use it as a checklist during code review or as rules-of-thumb when authoring new code.

How this skill works

The skill inspects code and discussions for common maintainability smells: poor names, oversized functions or classes, misleading comments, weak error handling, and brittle boundaries with third-party code. It maps issues to prioritized rules (meaningful names, functions, comments, formatting, error handling, objects, boundaries, classes, tests, emergence) and suggests concrete fixes and refactor directions. Recommendations are language-agnostic but include TypeScript-relevant examples and modern corrections to the original guidance.

When to use it

During code reviews to flag readability and design issues
When naming variables, functions, classes, or files
While refactoring to reduce complexity and improve intent clarity
When writing unit tests or improving test quality
When wrapping or interacting with third-party libraries

Best practices

Prefer intention-revealing names and avoid misleading abbreviations
Keep functions small, focused, and at a single level of abstraction
Express intent in code rather than relying on explanatory comments
Separate happy path logic from error handling and provide contextual errors
Wrap third-party APIs behind clear boundaries and add learning tests
Keep classes cohesive and organize for likely change

Example use cases

Review a pull request to replace cryptic names and inline comments with clearer abstractions
Refactor a large function into smaller single-purpose functions and improve argument lists
Convert null-returning APIs to explicit Result/Option patterns to avoid null-related bugs
Wrap a vendor SDK behind an adapter and add tests that document edge behavior
Rework tests to follow Build-Operate-Check and ensure one logical assertion per test

FAQ

Does this replace language-specific linters or formatters?

No. Use linters and formatters for automated style checks; this skill focuses on higher-level design, naming, and maintainability rules that linters cannot fully enforce.

How strict should teams be about every rule?

Prioritize critical rules (meaningful names, functions, error handling). Apply others pragmatically based on impact, team conventions, and delivery risks.