docs: fold stocktake rule guidance into common rules

This commit is contained in:
Affaan Mustafa
2026-04-05 15:49:43 -07:00
parent 31afed5b5d
commit adebf3e30b
3 changed files with 71 additions and 0 deletions

View File

@@ -12,6 +12,26 @@ CORRECT: update(original, field, value) → returns new copy with change
Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
## Core Principles
### KISS (Keep It Simple)
- Prefer the simplest solution that actually works
- Avoid premature optimization
- Optimize for clarity over cleverness
### DRY (Don't Repeat Yourself)
- Extract repeated logic into shared functions or utilities
- Avoid copy-paste implementation drift
- Introduce abstractions when repetition is real, not speculative
### YAGNI (You Aren't Gonna Need It)
- Do not build features or abstractions before they are needed
- Avoid speculative generality
- Start simple, then refactor when the pressure is real
## File Organization
MANY SMALL FILES > FEW LARGE FILES:
@@ -36,6 +56,28 @@ ALWAYS validate at system boundaries:
- Fail fast with clear error messages
- Never trust external data (API responses, user input, file content)
## Naming Conventions
- Variables and functions: `camelCase` with descriptive names
- Booleans: prefer `is`, `has`, `should`, or `can` prefixes
- Interfaces, types, and components: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- Custom hooks: `camelCase` with a `use` prefix
## Code Smells to Avoid
### Deep Nesting
Prefer early returns over nested conditionals once the logic starts stacking.
### Magic Numbers
Use named constants for meaningful thresholds, delays, and limits.
### Long Functions
Split large functions into focused pieces with clear responsibilities.
## Code Quality Checklist
Before marking work complete: