clean-code

name

clean-code

description

Apply clean code principles when generating or modifying implementation code. Enforces function focus, naming clarity, complexity management, error handling, and self-documenting style. Use when the user mentions 'clean code', 'code quality', 'coding guidelines', or 'implementation quality'. Loaded automatically by the code-generating molecules (code-forge, refactor-safely, bug-fix). This skill governs the craft of writing individual code units -- not architecture (see architecture), not security posture (see secure-coding), not test structure (see test-quality), and not refactoring workflows (see refactor-safely).

Clean Code

Config Resolution

Projects can customize this skill's standards. Resolution order:

1. Read .lattice/config.yaml in the repo root.
2. If found, check paths.clean_code for a custom document path.
3. If a custom document exists at that path, read it and check its YAML frontmatter for mode:
   • mode: override: the custom document has full precedence. Use it instead of the embedded defaults. It must be comprehensive -- treat it as the sole reference.
   • mode: overlay (or no mode field): read the embedded ./references/defaults.md first, then apply the custom document's sections on top. A custom section replaces the matching default section (matched by exact heading); new sections append after the defaults.
4. If a custom path is configured but no document exists at it → tell the user which configured path is missing, then fall back to ./references/defaults.md.
5. If there is no config file or no paths.clean_code key, read ./references/defaults.md.
6. Language adaptation: if paths.language_idioms is set in the config and the document exists, read it and adapt the defaults using these sections:
   • "Error Handling" → adapt §8 (Error Handling) patterns to the language's idioms. Language idioms take precedence over the pseudocode defaults.
   • "Type System & Object Model" → adapt §1 (Single Responsibility) cohesion guidance to the language's constructs (e.g., struct vs class).
   • "Naming Conventions" → adapt §4 (Meaningful Naming) patterns to the language's conventions.
   • "Parameter & Function Design" → adapt §2 (Small, Focused Functions) and §5 (Parameter Design) to the language's capabilities.
   • "Dependency Management" → adapt §9 (Test-Friendly Code) dependency-injection patterns to the language's idioms.

Self-Validation Checklist

STOP after generating each component. Verify ALL checks. Fix every failed check before presenting. Judgment calls → present options (see Ambiguity Signals).

1. SINGLE RESPONSIBILITY: Can you describe each function without "and"? If not → extract a separate function.
2. SIZE: Is each function under the size threshold from the loaded doc (~20 lines default)? If not → extract a sub-operation into its own named function.
3. COMPLEXITY: Is cyclomatic complexity under the threshold from the loaded doc (~10 default)? If not → flatten with a guard clause or extract a branch.
4. ABSTRACTION LEVEL: Does each function operate at one level of abstraction? If high-level logic mixes with low-level detail → extract the detail.
5. NAMING: Does each function/variable name reveal intent without needing surrounding context? If not → rename to be self-documenting.
6. PARAMETERS: Is the parameter count under the threshold from the loaded doc (4 default)? If not → group parameters into an object.
7. PRIMITIVE OBSESSION: Would a string/number/boolean be clearer as a named type? If so → introduce a parameter object or typed wrapper.
8. ERROR HANDLING: Does every fail-able operation have explicit handling with an actionable message? Is it handled at the right level?

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

All checks pass → state "Passes clean-code. [next step]."

Active Anti-Pattern Scan

After the checklist, scan for each of these. Any box you can check → fix before presenting.

• God Function: a function exceeds ~30 lines doing multiple things; describing it requires "and" → extract focused functions.
• Deep Nesting: three or more levels of indentation → flatten with early returns / guard clauses.
• Cryptic Naming: variables like d, tmp2, processData → rename to reveal intent.
• Long Parameter Lists: five or more parameters → group into an object or split the function.
• Premature Abstraction: a utility extracted from only two similar blocks → inline it until the Rule of Three (third instance with the same reason to change).
• Swallowed Errors: empty catch blocks, generic "something went wrong" messages, silent null returns → handle explicitly.
• Comments as Deodorant: a comment explains convoluted code instead of the code being fixed → rename to self-document; keep only "why" comments, remove "what" comments.
• Hidden Side Effects: a function named getX also writes a cache or sends notifications → rename or separate the concern.
• Dead Code: commented-out blocks, unused imports, unreachable branches → delete them (version control preserves history).
• Untestable Logic: side effects tangled with business logic; unit testing requires mocking I/O → push side effects to the boundary, extract pure functions, inject dependencies.

Ambiguity Signals

Multiple valid outcomes exist. Present the options rather than silently choosing. If framework:collaborative-judgment is loaded, use its presentation format. See ./references/defaults.md for resolution guidance on each signal below.

• Single Responsibility: two tightly-coupled sequential operations may be one responsibility (a pipeline), not two. The "and" test catches true violations AND false positives.
• Function Size: near-threshold size (20–30 lines) with one clear purpose -- extraction may create five unclear smaller functions. Present the tradeoff.
• DRY vs Premature Abstraction: two identical blocks may serve different purposes and diverge independently. Until a third instance with the same reason to change appears, this is genuinely ambiguous.
• Error Handling Strategy: exception vs Result type vs error codes depends on language idiom and team convention, not on universal rules.