# Coding style

> Applies when: writing or editing code; naming, reuse, guard clauses, readability.

Write code the next engineer can read without you in the room. Match the project's
existing idiom first; these rules fill the gaps.

## Names reveal intent
- A name should answer *what is this and why*. `daysSinceLastModification`, not `d`.
- Avoid generic verbs that hide intent: `process()`, `handle()`, `doWork()`, `manage()`.
- Be consistent: the same concept gets the same word across the codebase. Don't alias
  `user` / `account` / `member` for one thing.

## Functions do one thing
- One responsibility per function; if you need "and" to describe it, split it.
- Make edge cases explicit rather than implicit in clever control flow.

## Guard clauses over nested pyramids

Handle unwanted cases first and return early; keep the success path flat.

## Comments explain *why*, not *what*
- Self-explanatory code beats a comment restating it; delete commented-out code. The
  full comment do-not list (what-comments, tutorial noise, ownerless TODOs, edit-narration,
  hedging) is owned by [`anti-ai-slop.md`](../../../rite-polish/reference/anti-ai-slop.md)
  § Code anti-slop — one canonical list, consumed by build, polish, and review.

## Simplicity
- Prefer the simplest thing that works. Don't add abstraction before you have two real
  callers; premature generalization is a cost, not a saving.
- Delete dead code you created; don't leave TODOs or stray debug logs in shipped code.

## Reuse before you write
Before adding a new util, helper, hook, type, component, or formatter, **search** for an
existing one. Search by *problem shape*, not just name — the same problem solved under
different names is still an existing implementation, and the hardest duplicates to spot
are the renamed and reshaped ones. **Reuse → extend → build new**, in that order. Don't
re-implement what the project (or stdlib) already provides. If forcing reuse would
distort the existing thing's shape, build a sibling and consolidate later: duplication
is cheaper than the wrong abstraction (AHA). When a plan or slice adds a new
implementation, name the nearest existing analog it considered — or record `none found`.

## Edit reliably, change only what's asked
- **No elision.** Never write `// ... rest unchanged` / `# ... existing code` in place of an
  edit: emit the whole coherent function. Don't anchor an edit on line numbers; match on the
  surrounding code. If an edit fails to apply, **re-read the file before retrying**. It may
  have changed under you.
- **Do what's asked, no more, and no less.** Don't improve, comment, or refactor code unrelated
  to the task while you're in the file (feature scope). And never leave a comment describing code
  you didn't write: implement it.
- **Never hand-edit a manifest or lockfile.** Add / update / remove dependencies through the
  package manager (`npm install`, `pip install`, `go get`, `cargo add`) so the lockfile stays
  consistent: don't paste a version into `package.json` / `requirements.txt` by hand.