typescript-clean-code

# Clean Code ## The twelve change-shape smells Shotgun Surgery · Feature Envy · Data Clumps · Long Method · Divergent Change · Duplicated Code · Large Class · Long Parameter List · Primitive Obsession · Message Chains · Dead Code · Speculative Generality You know each one and its refactoring. The value is the checklist, not the definitions — without the names a diff "looks fine"; with them you find the shape. Run all twelve against any change you review or write. ## The smell catalog has four layers Each examines a different unit, so each sees what the others miss. | Load | Unit | For | |------|------|-----| | `references/smells/tooling.md` | the repository | **First, in every review.** Which smells a linter decides, so those become one "wire this into CI" finding instead of twenty hand-written ones | | `references/smells/rules.md` | a line, a function | Per-line heuristics (C/E/F/G/N/T), plus the review posture and severity vocabulary that govern all four layers | | `references/smells/fowler.md` | a modification | The twelve above — detection question, TypeScript remedy, and **when NOT to fix** for each | | `references/smells/typescript.md` | a type | TS1-TS10: `any` leakage, assertion versus validation, exhaustiveness, strictness flags, branded types | A diff can satisfy every rule in `rules.md` and still be badly shaped — that is what `fowler.md` is for. Reviewing a change means all four. ## Review posture Three rules that change output more than any catalog entry. Full text in `references/smells/rules.md` → "Review posture". 1. **Approve when the change improves code health**, not when it is perfect. There is no perfect code, only better code. 2. **A correct finding nobody acts on is a false positive.** Scan broadly, report selectively — three actionable findings beat twenty true ones. 3. **Mark polish as ignorable.** Conventional Comments labels — `issue`, `suggestion`, `nitpick`, `question`, `praise` — with `(blocking)` / `(non-blocking)`. An author who cannot tell which comments are optional treats all of them as mandatory, or none of them. **A review is done when** all four layers have run, every surviving finding carries a label and (for an `issue`) a fix, and the report states how many findings were cut as unlikely to be acted on. ## Contested rules Three rules in these references are positions with live counter-arguments, marked **contested** where they appear. Present both sides and prefer the author's demonstrated reasoning over the number: - **Function length** — `references/functions/rules.md` Rule 1. Detect by *"can I name each section?"*; the "2-5 lines" figure over-extracts when applied literally. - **Comments** — `references/comments/rules.md`. Keep rationale, invariants, and non-obvious why; delete restatement and stale comments. - **G23 polymorphism** — `references/smells/rules.md`. An exhaustive `switch` over a discriminated union is idiomatic TypeScript, not a smell. ## Workflows Load the `workflow.md`, then its step files in order. Each step names the references it needs and updates `stepsCompleted` in the output document's frontmatter, so a compacted context resumes from the last completed step via `step-01b-continue.md`. | Workflow | For | |----------|-----| | `workflows/code-review/workflow.md` | Reviewing code for quality | | `workflows/pr-review/workflow.md` | Reviewing pull requests | | `workflows/refactoring/workflow.md` | Safe refactoring with tests (step 3 sweeps all twelve; steps 5-8 loop) | | `workflows/tdd.md` | Test-driven development cycle | | `workflows/new-feature.md` | Building new functionality | | `workflows/bug-fix.md` | Fixing bugs properly | | `workflows/test-strategy.md` | Planning test coverage | | `workflows/estimation.md` | Estimating tasks (PERT) | | `workflows/deadline-negotiation.md` | Handling unrealistic deadlines | ## References `references/<topic>/` holds `rules.md` (the rules), `examples.md` (curated TypeScript bad/good pairs — prefer these over inventing your own), and `knowledge.md` (concepts). **Code quality**: naming · functions · classes · comments · error-handling · unit-tests · formatting · smells **Professional practice**: professionalism · saying-no · commitment · coding-practices · tdd · practicing · acceptance-testing · testing-strategies · time-management · estimation · pressure · collaboration Load the topic's `rules.md` before advising on it, and cite the rule you applied — the design problem it names, not the metric that pointed at it. Where a reference contradicts your general knowledge, the reference wins: it carries this skill's TypeScript adaptations and thresholds. `guidelines.md` maps symptom → reference file and task → workflow.