Developer

# Software Development Rules ## Code Quality - Readable code beats clever code — you'll read it 10x more than write it - Functions do one thing — if you need "and" to describe it, split it - Name things by what they do, not how — implementation changes, purpose doesn't - Delete dead code — version control remembers, codebase shouldn't carry weight - Consistent style matters more than which style — match the project ## Debugging - Read the error message completely — the answer is often in there - Reproduce before fixing — if you can't trigger it, you can't verify the fix - Binary search: comment out half the code to find the problem half - Check the obvious first — typos, wrong file, stale cache, wrong environment - Print/log liberally when stuck — assumptions are usually wrong ## Testing - Test behavior, not implementation — tests shouldn't break when you refactor - One assertion per test when possible — failures point to exact problem - Name tests as sentences describing expected behavior — readable test names are documentation - Mock external dependencies, not internal logic — integration points are boundaries - Fast tests run often, slow tests get skipped — optimize for feedback speed ## Error Handling - Fail fast and loud — silent failures create debugging nightmares - Catch specific exceptions, not generic — different errors need different handling - Log enough context to debug — error type alone isn't enough - User-facing errors should be helpful — "something went wrong" helps nobody - Don't catch exceptions you can't handle — let them bubble up ## Architecture - Start simple, add complexity when needed — premature abstraction wastes time - Separate concerns — UI, business logic, data access are different responsibilities - Dependencies flow inward — core logic shouldn't know about frameworks - Configuration separate from code — environment-specific values externalized - Document decisions, not just code — why matters more than what ## Code Review - Review for understanding, not just correctness — if you can't follow it, others won't - Ask questions instead of making demands — "what if..." opens discussion - Small PRs get better reviews — 500 lines gets skimmed, 50 lines gets read - Approve when good enough, not perfect — progress beats perfection - Catch bugs early, style issues are secondary — priorities matter ## Performance - Measure before optimizing — intuition about bottlenecks is usually wrong - Optimize the hot path — 90% of time is spent in 10% of code - Database queries are usually the bottleneck — check there first - Caching solves many problems — but cache invalidation creates new ones - Premature optimization wastes time — make it work, then make it fast ## Dependencies - Evaluate before adding — every dependency is code you don't control - Pin versions — "latest" breaks builds unpredictably - Check maintenance status — abandoned packages become security risks - Fewer dependencies is better — each one adds supply chain risk - Read changelogs before upgrading — breaking changes hide in minor versions ## Working in Existing Codebases - Match existing patterns — consistency beats personal preference - Improve incrementally — boy scout rule, leave it better than you found it - Understand before changing — read the tests, check git history - Don't refactor while fixing bugs — separate commits, separate PRs - Legacy code works — respect the battle scars ## Communication - Commit messages explain why, not what — diff shows what changed - Document surprising behavior — future developers need context - Ask before large refactors — alignment prevents wasted work - Estimate with ranges, not points — "2-4 days" is more honest than "3 days" - Say "I don't know" when you don't — guessing wastes everyone's time