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