When this skill is activated, always start your first response with the 🧢 emoji.

Clean Code

Clean Code is a set of principles and practices from Robert C. Martin (Uncle Bob) for writing software that is readable, maintainable, and expressive. The core idea is that code is read far more often than it is written, so optimizing for readability is optimizing for productivity. This skill covers the Clean Code book's principles, SOLID object-oriented design, and test-driven development - giving an agent the judgment to write, review, and refactor code the way a disciplined craftsman would.

When to use this skill

Trigger this skill when the user:

• Asks to review code for quality, readability, or maintainability
• Wants to refactor a function, class, or module to be cleaner
• Needs help naming variables, functions, or classes
• Asks about SOLID principles or how to apply them
• Wants to decompose a large function or class
• Asks to identify code smells or technical debt
• Wants to write tests using TDD (red-green-refactor)
• Needs to improve error handling patterns

Do NOT trigger this skill for:

• Performance optimization (clean code prioritizes readability, not speed)
• Architecture decisions at the system level (use clean-architecture skills instead)

Key principles

1. The Boy Scout Rule - Leave the code cleaner than you found it. Every commit is an opportunity to improve a name, extract a helper, or remove dead code.

2. Readability is king - Code should read like well-written prose. If a reader needs to pause and re-read a line, that line needs work. Clever code is bad code.

3. Single Responsibility at every level - Every function does one thing. Every class has one reason to change. Every module has one area of responsibility.

4. Express intent, don't document it - The code itself should explain what and why. Comments that explain "what" the code does indicate the code failed to communicate. Reserve comments for "why" something non-obvious was chosen.

5. Small is beautiful - Functions should be 5-20 lines. Classes should be small enough to describe in one sentence. Files should fit a mental model.

Core concepts

Clean Code rests on a hierarchy of concerns, from the smallest unit to the largest:

Names are the most fundamental tool. A good name eliminates the need for comments, makes intent obvious, and prevents misuse. Names should be intention-revealing, pronounceable, and searchable. See references/naming-guide.md.

Functions are the building blocks. Each function should do one thing, operate at one level of abstraction, and have as few arguments as possible. The "stepdown rule" means code reads top-to-bottom like a newspaper - high-level summary first, details below.

SOLID principles govern class and module design. They prevent rigid, fragile code that breaks in unexpected places when changed. See references/solid-principles.md.

Code smells are surface indicators of deeper structural problems. Recognizing smells is the first step to refactoring. See references/code-smells.md.

Tests are the safety net that enables fearless refactoring. TDD (test-driven development) ensures tests exist before code and that code is only as complex as needed. See references/tdd.md.

Common tasks

Review code for Clean Code violations

Walk through the code looking for violations in this priority order:

1. Naming - Are names intention-revealing? Can you understand the code without reading comments?
2. Function size - Any function over 20 lines? Does it do more than one thing?
3. Abstraction levels - Does the function mix high-level logic with low-level detail?
4. Duplication - Any copy-paste code or structural duplication?
5. Error handling - Are errors handled with exceptions, not return codes? Any null returns?

Before (violations):

// Check if user can access the resource
function check(u, r) {
  if (u != null) {
    if (u.role == 'admin') {
      return true;
    } else if (u.perms != null) {
      for (let i = 0; i < u.perms.length; i++) {
        if (u.perms[i].rid == r.id && u.perms[i].level >= 2) {
          return true;
        }
      }
    }
  }
  return false;
}

After (clean):

function canUserAccessResource(user, resource) {
  if (!user) return false;
  if (user.isAdmin()) return true;
  return user.hasPermissionFor(resource, Permission.READ);
}

Refactor a long function

Apply the Extract Method pattern. Identify clusters of lines that operate at the same level of abstraction and give them a name.

Before:

def process_order(order):
    # validate
    if not order.items:
        raise ValueError("Empty order")
    if not order.customer:
        raise ValueError("No customer")
    for item in order.items:
        if item.quantity <= 0:
            raise ValueError(f"Invalid quantity for {item.name}")

    # calculate totals
    subtotal = sum(item.price * item.quantity for item in order.items)
    tax = subtotal * 0.08
    shipping = 5.99 if subtotal < 50 else 0
    total = subtotal + tax + shipping

    # charge
    payment = gateway.charge(order.customer.payment_method, total)
    if not payment.success:
        raise PaymentError(payment.error)

    # send confirmation
    send_email(order.customer.email, "Order confirmed", f"Total: ${total:.2f}")

After:

def process_order(order):
    validate_order(order)
    total = calculate_total(order)
    charge_customer(order.customer, total)
    send_confirmation(order.customer, total)

Each extracted function is independently readable, testable, and reusable.

Improve naming

Apply these rules by entity type:

See references/naming-guide.md for the full guide.

Apply SOLID principles

When a class is hard to change, test, or reuse, check it against SOLID:

• Single Responsibility - Does this class have more than one reason to change? Split it.
• Open/Closed - Can you extend behavior without modifying existing code? Use polymorphism.
• Liskov Substitution - Can subtypes replace their parent without breaking things?
• Interface Segregation - Are clients forced to depend on methods they don't use? Split the interface.
• Dependency Inversion - Do high-level modules depend on low-level details? Inject abstractions.

See references/solid-principles.md for detailed examples and when NOT to apply each.

Write clean tests with TDD

Follow the red-green-refactor cycle:

1. Red - Write a failing test that defines the desired behavior
2. Green - Write the minimum code to make it pass
3. Refactor - Clean up both production and test code

Tests should follow the FIRST principles (Fast, Independent, Repeatable, Self-validating, Timely) and use the Arrange-Act-Assert structure.

See references/tdd.md for the full guide.

Clean up error handling

Replace error codes with exceptions. Never return or pass null.

Before:

public int withdraw(Account account, int amount) {
    if (account == null) return -1;
    if (amount > account.getBalance()) return -2;
    account.debit(amount);
    return 0;
}
// Caller: if (withdraw(acct, 100) == -2) { ... }

After:

public void withdraw(Account account, int amount) {
    Objects.requireNonNull(account, "Account must not be null");
    if (amount > account.getBalance()) {