Clean Code

Clean Code

This skill covers writing code that is easy to read and change, and — just as important — avoiding the over-engineering that makes code harder to read and change in the name of "best practices." Both halves matter together: clean code is simple code, not merely well-decorated code.

Workflow for Writing or Reviewing Code

1. Scope the change — Identify exactly what was asked for. Note what's out of scope before writing anything.
2. Reach for the simplest solution first — Prefer the direct, obvious implementation over a general or configurable one, unless a concrete current need justifies more.
3. Name things for their purpose — Choose names that reveal intent before writing the body of a function or the shape of a type.
4. Keep functions single-purpose — If a function needs a comment to explain what it does, split it.
5. Remove duplication deliberately — Extract shared logic only once it's actually duplicated (see Rule of Three below), not preemptively.
6. Write or update tests — Cover the new behavior and the edge cases it introduces.
7. Verify scope before delivery — Confirm only the requested code changed, check for a simpler approach you might have missed, and confirm no unrequested files were touched.

Meaningful Names

• Variables, functions, and classes should reveal their purpose from the name alone.
• Names should explain why something exists and how it's used, not just its type or contents (activeUserIds, not list1).
• Avoid abbreviations unless they're universally understood in the domain (id, url — fine; usrCfgTmp — not fine).

Constants Over Magic Numbers

• Replace hard-coded values with named constants (MAX_RETRY_COUNT = 3, not a bare 3 three call sites later).
• Use descriptive constant names that explain the value's purpose, not just its value.
• Keep constants at the top of the file or in a dedicated constants module when shared across files.

Smart Comments

• Don't comment on what the code does — make the code self-documenting through naming and structure instead.
• Use comments to explain why something is done a certain way, especially when the reason isn't visible in the code (a workaround for a library bug, a non-obvious ordering requirement).
• Document public APIs, genuinely complex algorithms, and non-obvious side effects.

Single Responsibility

• Each function should do exactly one thing.
• Functions should be small and focused enough to be understood without scrolling.
• If a function needs a comment to explain what it does, that's a signal to split it into named sub-functions instead.

DRY — Don't Repeat Yourself

• Extract repeated code into reusable functions once the repetition is real, not anticipated.
• Share common logic through a proper abstraction — a shared function or module, not copy-paste with tweaks.
• Maintain a single source of truth for any given piece of business logic or configuration value.

Encapsulation

• Hide implementation details behind a clear interface; callers shouldn't need to know how a thing works to use it.
• Move nested conditionals into well-named functions or guard clauses instead of deep if/else trees.

// Before
function canCheckout(cart) {
  if (cart.items.length > 0) {
    if (cart.user.isVerified) {
      if (cart.total <= cart.user.creditLimit) {
        return true;
      }
    }
  }
  return false;
}

// After
function canCheckout(cart) {
  const hasItems = cart.items.length > 0;
  const isWithinCreditLimit = cart.total <= cart.user.creditLimit;
  return hasItems && cart.user.isVerified && isWithinCreditLimit;
}

Clean Structure

• Keep related code together (a feature's components, hooks, and styles in one directory, not scattered by file type).
• Organize code in a logical hierarchy that mirrors how the domain is understood.
• Use consistent file and folder naming conventions across the codebase.