Framework Selection
Pick the framework that's boring and well-documented over the one that's novel and clever.
Why
A framework is the substrate every line of your code sits on — its bugs become your bugs, its abstractions become your mental model, its upgrade path becomes your weekend. A boring, well-documented framework (Express, Spring, Django) has known bugs (all found), known patterns (all Stack Overflowed), and a long support horizon. A novel framework has unknown bugs, sparse docs, and may be abandoned in 2 years. The novelty is fun for the author and painful for the team that inherits it. Framework selection should optimize for team productivity and longevity, not for the author's curiosity.
When
At service creation. Takes 2-4 hours to evaluate. Revisit only if the framework is end-of-life or blocking a critical feature.
How
1. List candidate frameworks for the language (see language-selection) 2. For each, score on: - Maturity: > 3 years old, stable API, used by production systems at scale - Documentation: comprehensive, examples, active community (Stack Overflow tags) - Maintenance: recent releases, responsive maintainers, security patch speed - Hiring: can we find engineers who know it? - Fit: does it match our problem (web, CLI, batch, real-time)? 3. Eliminate any that score low on maturity or maintenance — these are disqualifiers 4. Among the rest, prefer the most boring (most users, most docs, fewest surprises) 5. Prototype the riskiest feature in the top 2 (1 day each) to confirm fit 6. Decide; document the reasoning and the alternatives considered in an ADR
Example
Service: internal admin API (Go) Candidates: - Gin: mature (10yr), excellent docs, huge community, boring ✓ - Echo: mature, good docs, smaller community - Fiber: novel (Express-like), fast, fewer users, newer - net/http stdlib: most boring, fewest features, most verbose Scores (maturity/docs/maint/hiring/fit, 1-5): Gin: 5/5/5/5/5 = 25 Echo: 5/4/5/4/5 = 23 Fiber: 3/3/4/2/5 = 17 stdlib: 5/5/5/5/3 = 23 Decision: Gin. Most boring, best docs, easiest to hire for. Fiber's speed advantage is irrelevant for an internal admin API.
Common Problems
- ⚠Choosing the novel framework because it's 'more modern' — modern means unknown bugs and sparse docs; boring means solved problems and help on Stack Overflow.
Best Practices
- ✓Prefer the framework the team already knows — the productivity of familiarity beats the theoretical advantages of a better framework you'd have to learn.
- ✓Check the framework's last release date and issue response time before choosing — an unmaintained framework is a liability, not an asset.