code-hygiene

# Code Hygiene Standards

## Core Principles

- **Comments explain WHY, not WHAT** - Code shows what through clear naming
- **Self-documenting code** - Descriptive names > comments
- **Git captures history** - Never add "moved from X" or "extracted from Y" comments

## Comment Rules

**Never write:**
- Archaeological: "Extracted from X to reduce complexity"
- Motion tracking: "Moved from Y on DATE"
- Obvious: "Increment counter" above `counter += 1`
- Vague TODOs: "TODO: fix this" (add ticket number + context)
- Commented-out code (Git remembers)

**Do write:**
- Design rationale: "Binary search because dataset >10k items"
- Security markers: "SECURITY: Validate path to prevent traversal"
- Performance constraints: "Must complete <50ms for 60Hz tick"
- External quirks: "GitHub API returns max 100 items per page"
- Actionable TODOs: "TODO(#423): Replace with spatial hash for >1000 entities"

## File Size Limits

- **>500 lines**: Stop. Refactor before adding code.
- **>300 lines + new code**: Ask about extraction first.

## Responsibility Check

Before adding code: Does this add a different responsibility? If yes, suggest where it should live instead.

## Naming

- Descriptive: `validate_path_within_boundary` not `check_path`
- No vague names: `data`, `info`, `temp`, `mgr`, `handler`
- Booleans: `is_valid`, `has_permission`, `can_edit`
- Constants: `TIMEOUT_MS` (include units)

## Refactoring Hygiene

- Delete "extracted from" comments after moving code
- Delete code completely (don't comment out)
- Remove unused imports
- Update all call sites atomically

**Remember**: Every line should serve a purpose. Delete ruthlessly. Name precisely.