clean-code

# Clean Code

## Config Resolution

Skill support project custom. Order:

1. Look `.lattice/config.yaml` in repo root
2. If found, check `paths.clean_code` for custom doc path
3. If custom path exist, read doc and check YAML frontmatter for `mode`:
   - **`mode: override`** (or no mode): Custom doc full precedence. Use instead embedded default. Must be comprehensive -- sole reference.
   - **`mode: overlay`**: Read embedded `./references/defaults.md` first, then apply custom doc sections on top. Custom sections replace matching sections in default (matched by heading). New sections appended after default.
4. If no config/path/file, read `./references/defaults.md`
5. **Language adaptation**: If `paths.language_idioms` exist in config, read that document and adapt defaults using these sections:
   - **"Error Handling"** → adapt §8 (Error Handling) patterns to language idioms. Language idioms take precedence over pseudocode defaults.
   - **"Type System & Object Model"** → adapt §1 (Single Responsibility) cohesion guidance to language constructs (e.g., struct vs class).
   - **"Naming Conventions"** → adapt §4 (Meaningful Naming) patterns to language conventions.
   - **"Parameter & Function Design"** → adapt §2 (Small, Focused Functions) and §5 (Parameter Design) to language capabilities.
   - **"Dependency Management"** → adapt §9 (Test-Friendly Code) DI patterns to language idioms.

Default ship with skill. Opinionated best practice. Work out of box. Override only when team have different standard.

## Self-Validation Checklist

STOP after generate each component. Verify ALL before proceed. If check clearly fail, fix before present. If judgment call with multiple valid approach (see Ambiguity Signals), flag it — present options and reasoning.

1. **SINGLE RESPONSIBILITY**: Describe each function without "and"? If not → extract separate function.
2. **SIZE**: Each function under size threshold per loaded doc (~20 lines default)? If not → extract sub-operation into named function.
3. **COMPLEXITY**: Cyclomatic complexity under threshold per loaded doc (~10 default)? If not → flatten with guard clause, extract branch.
4. **ABSTRACTION LEVEL**: Each function operate at one level? If high-level mixed with low-level → extract detail.
5. **NAMING**: Function/variable name reveal intent without context? If not → rename self-documenting.
6. **PARAMETERS**: Parameter count under threshold per loaded doc (4 default)? If not → group into object.
7. **PRIMITIVE OBSESSION**: String/number/boolean clearer as named type? If so → introduce parameter object or typed wrapper.
8. **ERROR HANDLING**: Every fail-able operation have explicit handling with actionable message? Handled at right level?

**Project-specific checks:** If loaded doc (from Config Resolution) contains a Validation Checklist section (§10), apply those checks as additional project-specific validation after the checklist above.

## Active Anti-Pattern Scan

After checklist, scan for these. If find, fix before present.

- [ ] **God Function**: Function exceed ~30 lines doing multiple thing; description need "and" → extract focused function
- [ ] **Deep Nesting**: Three+ level indentation → flatten with early return/guard clause
- [ ] **Cryptic Naming**: Variable like `d`, `tmp2`, `processData` → rename reveal intent
- [ ] **Long Parameter Lists**: Five+ parameter → group into object or split function
- [ ] **Premature Abstraction**: Utility extracted from only two similar block → inline until Rule of Three with same reason to change
- [ ] **Swallowed Errors**: Empty catch, generic "something went wrong," silently return null → handle explicitly
- [ ] **Comments as Deodorant**: Comment explain convoluted code instead refactor → rename self-documenting; keep only "why" comment, remove "what"
- [ ] **Hidden Side Effects**: Function named `getX` also write cache/send notification → rename or separate
- [ ] **Dead Code**: Commented-out block, unused import, unreachable branch → delete (version control preserve)
- [ ] **Untestable Logic**: Side effect tangled with business logic; unit test need mock I/O → push side effect to boundary, extract pure function, inject dependency

## Ambiguity Signals

Multiple valid outcome. Present option rather than silently choose. See `./references/defaults.md` for resolution guidance on each signal below.

- **Single Responsibility**: Two tightly-coupled sequential operation may be one responsibility (pipeline), not two. "And" test catch true violation AND false positive.
- **Function Size**: Near-threshold (20-30 lines) with one clear purpose -- extract may create five unclear smaller function. Present tradeoff.
- **DRY vs Premature Abstraction**: Two identical block may serve different purpose and diverge. Until third instance with same reason to change, genuinely ambiguous.
- **Error Handling Strategy**: Exception vs Result type vs error code depend on language idiom and team convention, not universal.

## Core Principle

Clean code about **craft writing individual unit** -- function, class, module. Distinct from architecture (govern where code live) and domain modeling (govern business rule). Apply during code generation, not post-generation review.

See `./references/defaults.md` for SRP pipeline nuance, size vs clarity thresholds, magic number extraction rules, boolean parameter patterns, DRY vs wrong abstraction heuristics, and error message guidelines.