Maintain Design Quality
Overview
Core Principle: If you're not making the design better, you're probably making it worse. Working code is not a high enough standard.
Discipline Requirement: Every modification is an opportunity to improve or degrade design. Resist quick fixes. Ask whether the current design is still optimal given the change you need to make.
Zero Tolerance: There is no acceptable threshold for making design worse. Even "small" compromises accumulate invisibly—dozens of tactical decisions compound into unmaintainable systems. Each change must improve or maintain design, never degrade it.
When to Use
- •Fixing bugs in existing code
- •Adding features to existing modules
- •Extending or modifying existing behavior
- •Working under time pressure ("quick fix")
- •Touching legacy code
- •User says: "fix bug", "modify", "extend", "quick change", "add to existing"
When NOT to Use
- •Creating new modules from scratch (see: designing-deep-modules)
- •Evaluating code quality (see: reviewing-module-design)
- •Simplifying complex code (see: simplifying-complexity)
- •Improving clarity only (see: improving-code-clarity)
- •Performance optimization (see: optimizing-critical-paths)
Urgency Tiers
Not all changes need equal analysis. Match effort to impact:
| Tier | Examples | Required Analysis |
|---|---|---|
| Trivial | Typo fixes, whitespace, comment corrections | None—just do it |
| Minor | Bug fix <5 lines, config tweak, dependency bump | Quick check: does this fit cleanly? |
| Standard | New feature, refactoring, multi-file change | Full workflow: STOP-ASK-DECIDE-VERIFY |
| Emergency | Production down, security breach, data loss | Minimal fix + TODO + 24hr follow-up |
Emergency Bypass Criteria
Skip the normal workflow ONLY when ALL of these conditions are true:
- •Production is down RIGHT NOW (not "might break soon")
- •Users are actively impacted, security breach in progress, OR data loss occurring
- •The fix is minimal (rollback or single-line change)
- •You commit to returning for proper implementation within 24 hours
Emergency does NOT mean:
- •"Demo in 30 minutes" — That's planning failure
- •"CEO is asking" — Authority pressure ≠ emergency
- •"Team is blocked" — They can wait for you to think
- •"We need this fast" — Speed pressure is when discipline matters MOST
Emergency DOES mean:
- •Production is down and users are impacted NOW
- •Security vulnerability being exploited
- •Data corruption or loss occurring
Strategic Modification Workflow
code
BEFORE making any change to existing code: 1. RESIST the temptation to make a quick fix 2. ASK: "Is the current system design still the best one, given the change I need to make?" 3. IF NO: Refactor so you end up with the best possible design Goal: After this change, the system should have the structure it would have had if designed from the start with this in mind 4. IF YES: Make the change within the existing design But verify: does your change fit cleanly? 5. BEFORE COMMIT: Scan all changes to verify documentation reflects them
The Investment Mindset
| Approach | Short-Term | Long-Term |
|---|---|---|
| Tactical | 10-20% faster | Permanently slower (20%+ productivity loss) |
| Strategic | 10-20% slower | Benefits in months; eventually free |
Recommended investment: About 10-20% of development time on design improvements.
Why Strategic Wins
code
Tactical path: - Each "quick fix" adds small complexity - Complexities accumulate (dozens/hundreds of small things) - Eventually: system is hard to understand and modify - Result: development slows permanently Strategic path: - Each change improves or maintains design - Past investments save time for future investments - Eventually: strategic investments become FREE - Result: development accelerates over time
Design Evolution Principle
A system's design cannot be conceived correctly at the outset. The design of a mature system is determined more by changes made during evolution than by initial conception.
Implication: Every modification matters. Your changes ARE the design.
When Refactoring Seems Impractical
Even under tight deadlines, ask:
code
"Is this the best I can possibly do to create a clean system design, given my current constraints?"
| If... | Then... |
|---|---|
| Large refactoring is impractical | Look for alternatives that are almost as clean but faster |
| Cannot do proper cleanup now | Create accountability plan (see below) |
| Refactoring creates incompatibilities | Seek middle-ground solutions |
Never acceptable: Making the design worse without a plan to fix it.
Accountability for Deferred Refactoring
If you defer refactoring, it MUST be tracked:
code
1. CREATE a ticket/issue with specific scope 2. TIMEBOX: Must be addressed within 2 sprints (or equivalent) 3. ADD a code comment: // TODO(YYYY-MM-DD): [ticket-id] - [what needs fixing] 4. ESCALATE if 3+ deferrals exist in same area → refactoring becomes MANDATORY
"I'll do it later" without these steps = you won't do it.
When NOT to Refactor
Refactoring is not always the right choice:
| Scenario | Why Refactoring Hurts | What to Do Instead |
|---|---|---|
| Chesterton's Fence code | Looks bad but handles subtle edge cases | Investigate WHY before changing |
| Performance-critical paths | Clean abstractions add overhead | Document why it's intentionally ugly |
| Regulatory/audited code | Changes trigger expensive re-certification | Get explicit approval first |
| Legacy with no tests | Refactoring without tests is dangerous | Add tests first, or freeze |
| Code with external quirk dependencies | Other systems rely on undocumented behavior | Coordinate with dependents |
| Near end-of-life systems | Investing in dying code is waste | Document, don't improve |
| During incident response | Changing more increases blast radius | Minimal fix only |
| When you don't understand domain | "Better design" reflects misunderstanding | Learn first, refactor later |
Key question: Do I understand WHY the code is the way it is?
If no → investigate before refactoring.
Red Flags
| Red Flag | Symptom | What It Signals |
|---|---|---|
| Quick Fix Mentality | "Just make it work for now" | Tactical programming—design will degrade |
| Complexity Creep | Adding special cases, conditionals, dependencies | Design is getting worse, not better |
| Patch Stacking | Workarounds on top of workarounds | Technical debt accumulating |
| Tactical Tornado | Very fast developer leaving messes | Others will pay for their speed |
| Stale Comments | Comments no longer match code | Trust erosion; documentation debt |
| Deferred Cleanup | "We'll refactor later" | Later never comes; delay becomes permanent |
Anti-Rationalization Table
Classic Rationalizations
| Tempting Shortcut | Why It Feels Right | Why It's Wrong |
|---|---|---|
| "Just make it work" | Faster now | Creates technical debt forever; 20%+ productivity loss |
| "Don't touch working code" | Risk averse | Prevents improvement; design decays anyway |
| "We'll refactor later" | Deferred pain | Later never comes; there's always another crunch |
| "This is just a quick fix" | Scope limiting | Quick fixes accumulate; complexity is incremental |
| "I don't have time" | Deadline pressure | 10-20% investment now saves more later |
| "It's not that bad" | Normalizing decay | Each small compromise adds up to major complexity |
| "Someone else will clean it up" | Delegation | You are that someone; it never happens |
Responsibility-Avoidance Rationalizations
| Tempting Shortcut | Why It Feels Right | Why It's Wrong |
|---|---|---|
| "I'm not the owner of this module" | Not my responsibility | If you're touching it, you're responsible for it |
| "The original author did it this way" | Appeal to authority | Original author might have been wrong, or context changed |
| "This matches the existing pattern" | Consistency | Consistently following a bad pattern spreads the problem |
| "I'm just copying what's in the other file" | Following example | You're spreading bad patterns across the codebase |
"It Doesn't Count" Rationalizations
| Tempting Shortcut | Why It Feels Right | Why It's Wrong |
|---|---|---|
| "This is temporary/experimental code" | It's throwaway | Nothing is as permanent as temporary code |
| "The tests pass" | Correctness verified | Passing tests ≠ good design; tests check behavior, not quality |
| "I'll document the tech debt" | I'm being responsible | Documentation is not remediation; debt still accrues interest |
| "This is behind a feature flag" | It's isolated | Feature flags don't quarantine design rot |
| "This is just a config change" | It's not real code | Config is code; complexity hides there too |
| "This is just glue code" | It's boilerplate | All code deserves design thought |
Misapplied Principles
| Tempting Shortcut | Why It Feels Right | Why It's Wrong |
|---|---|---|
| "Refactoring violates YAGNI" | Don't over-engineer | YAGNI applies to features, not code quality |
| "The code is already so bad my change can't make it worse" | Pragmatism | Nihilistic surrender; you can always make things worse |
| "The PR is already too big" | Keep PRs small | Split the PR; don't use size to excuse quality |
| "I need to ship to get feedback first" | Iterate fast | Design debt accrues before feedback arrives |
Comment Maintenance
When modifying code, keep comments synchronized:
| Rule | Why |
|---|---|
| Position comments close to code they describe | Developers see them when modifying |
| Avoid duplicating documentation | One source of truth; easier to maintain |
| Document each decision exactly once | Find the single most obvious place |
| Scan all changes before commit | Catch stale comments early |
| Use higher-level comments when possible | Resilient to minor code changes |
Technical Debt Reality
| Myth | Reality |
|---|---|
| "We'll pay it back" | Most technical debt is never fully repaid |
| "It's a fair trade" | Amount paid back exceeds amount borrowed |
| "Just this once" | Once you start, it's difficult to change |
| "Everyone does it" | Complexity accumulates rapidly if everyone programs tactically |
Quick Reference
code
EVERY TIME you modify existing code: 1. STOP - Resist the quick fix temptation 2. ASK - "Is this design still optimal for what I need?" 3. DECIDE: - Design is optimal? Make change cleanly - Design needs work? Refactor first - Can't refactor now? Plan when you will 4. VERIFY - Comments updated? Design improved or maintained? 5. COMMIT - Only when design is better or at least not worse THE RULE: "If you're not making the design better, you're probably making it worse." INVESTMENT MATH: - 10-20% slower now → faster forever - "Quick fix" now → 20%+ slower forever
References: aposd-foundations for complexity symptoms