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.

jsCopy code
// 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.

Avoiding Over-Engineering

• Only change what was asked. The simplest solution that satisfies the request comes first.
• When the right level of abstraction is unclear, ask rather than guessing toward the more elaborate option.
• Do not modify unrequested code, even if it looks improvable — a drive-by refactor in an unrelated function expands the review surface and the risk of the change.
• Do not add abstractions (interfaces, factories, plugin systems, config layers) without a concrete, current need. A single implementation doesn't need an interface "in case" a second one shows up later — that's speculative generality (YAGNI: "You Aren't Gonna Need It").
• Do not import a new dependency to solve a problem a few lines of existing code already solve.
• Do not rewrite entire files for small changes — a targeted diff is easier to review and safer to ship than a full-file rewrite.
• Do not add error handling for scenarios that cannot occur given the surrounding code's guarantees — defensive code for impossible states adds reading cost without adding safety.

Rule of Three

• Tolerate duplication the first two times a pattern appears.
• Extract an abstraction on the third occurrence, once the actual shape of the shared logic is clear — extracting after one or two instances often guesses wrong about what's actually shared.

Signs of Over-Engineering

• A configuration option that has only ever been set to one value.
• An interface with exactly one implementation and no test double that needs a second.
• A generic options object accreting fields for hypothetical future callers.
• A plugin/strategy pattern introduced before there are two strategies to switch between.

Code Quality Maintenance

• Refactor continuously in small steps rather than deferring cleanup to a dedicated "refactor sprint."
• Fix technical debt early, while the context for why the code looks the way it does is still fresh.
• Leave code cleaner than you found it, scoped to the area you're already touching — not as license to refactor unrelated files.

Testing

• Write a failing test before fixing a bug, so the fix is verified and the bug can't silently regress.
• Keep tests readable and maintainable — a test that's harder to understand than the code it tests has failed at its job.
• Test edge cases and error conditions explicitly, not just the happy path.

Version Control

• Write clear, specific commit messages that explain why a change was made.
• Make small, focused commits — one logical change per commit.
• Use meaningful branch names that describe the work, not the author or the date.

Before Delivery Checklist

• Only the requested code changed — no unrelated files touched.
• No abstraction was added without a concrete need that exists today.
• No dependency was added that duplicates something already available.
• A simpler approach was considered and ruled out, not just skipped.
• New behavior has test coverage, including at least one edge case.