Code quality pillars, goals, abstraction layers, and tradeoff thinking. Use when evaluating code quality, setting quality goals, choosing abstraction levels, making design tradeoffs, or auditing code against quality pillars. Covers readability, modularity, testability, reusability, and the principle of least astonishment.
| Goal | Question to Ask | Failure Mode |
|---|---|---|
| It works | Does it solve the problem correctly? | Bugs, unhandled edge cases, unmet requirements |
| It keeps working | Will it survive changes around it? | Brittle dependencies, no tests, hidden assumptions |
| It's adaptable | Can requirements change without a rewrite? | Rigid coupling, over-engineering, hardcoded assumptions |
| It doesn't reinvent the wheel | Are we reusing proven solutions? | Custom code for solved problems, duplicated effort |
| Pillar | What It Means | Key Technique |
|---|---|---|
| Readable |
| Other engineers can understand it quickly |
| Descriptive names, clean layers, consistent style |
| No surprises | Behavior matches expectations (POLA) | Explicit contracts, no magic values, no hidden side effects |
| Hard to misuse | Difficult to use incorrectly | Type safety, immutability, validated construction |
| Modular | Components can be swapped independently | Interfaces, DI, separation of concerns, cohesion |
| Reusable & generalizable | Solves problems broadly, not just one case | Focused parameters, generics, avoiding assumptions |
| Testable | Can be verified in isolation | Modularity enables testability; design for it from the start |
POLA = Principle of Least Astonishment. If a function does something a reasonable caller wouldn't expect, it's a bug in the design, even if it "works."
| Concern | Why It's Now Explicit | Original Coverage |
|---|---|---|
| Secure | Shift-left security; threat model at design time | Implicit in "works" |
| Efficient | Resource optimization is a design choice, not afterthought | Subsumed under "works" |
| Reliable | Explicit error recovery and graceful degradation | Subsumed under "keeps working" |
| Signal | Action |
|---|---|
| Same logic appears in 2+ places | Extract to shared function/class |
| Function can't be described in one sentence | Split into smaller functions |
| Class has method groups that use different fields | Consider splitting into separate classes |
| Changing one feature requires touching many files | Improve modularity and layer boundaries |
| Only one use case exists | Wait — don't abstract prematurely |
| Situation | Focus On | Rationale |
|---|---|---|
| Greenfield project | Modularity, clean interfaces | Foundation decisions compound; structure early |
| Legacy codebase | Testing, readability | Understand before changing safely |
| High-traffic service | Reliability, efficiency, testing | Production failures are expensive |
| Prototype / spike | Working code, speed | Validate the idea; plan to rewrite |
| Shared library / API | Hard to misuse, no surprises | You can't predict how consumers will use it |
| Security-sensitive code | Security, testability | Breaches are catastrophic and trust-destroying |