Lesson 0038 · Master Designer · Module 3

Short-Term Productivity vs Long-Term Maintainability

You may borrow from the future — every team does. The master's rule: record the loan. Debt that is invisible is never repaid; debt that is named gets a repayment plan.

Reading ≈ 9 minPractice ≈ 30 min

Mission tie-in: the final trade-off closes the Master Designer phase — maintainability is not the enemy of productivity; it is productivity, compounded. The Initiative Lead phase applies that judgment to a whole project.

Knowledge: the loan, the ledger, and the compounding

Ship the quick version now and the slow version later? That is a loan — you are borrowing future maintenance time to buy present shipping time. Loans are legitimate. What is never legitimate is a loan with no ledger entry: the debt exists, invisibly, and compounds through every future change (lesson 0035's flags, lesson 0037's skipped apparatus).

The ledger entry has three lines:

1. What was borrowed. The corner cut, named precisely: "the pricing logic lives in the endpoint, not the domain."
2. What it costs. The interest: "every pricing change now edits a route handler and needs a manual regression check."
3. The repayment. The trigger: "repay when the third pricing variant arrives."

# borrowed: a quick, coupled implementation
def endpoint(request: Request) -> Response:
    if request.json["tier"] == "gold":            # pricing logic in the route
        price = request.json["amount"] * 0.9
    ...
# ledger entry:
#   borrowed: pricing rules in the endpoint (not the domain)
#   interest: every pricing change edits routes + manual QA
#   repay when: third pricing variant arrives → extract PricingStrategy
#               (lesson 0004's shape, already visible)

And the compounding works the other way too: the clean code from Phase I isn't a luxury — it is future productivity purchased at small present cost. Ousterhout's point, now fully earned: a working system that's hard to change is not an asset, it's a liability that grows. The final summary of this course: maintainability is productivity over time, and every trade-off in this phase was the same trade in different clothing.

Worked: pricing one loan, and choosing which to repay

The pricing rule lives in the route handler because the first version needed to ship for a launch date. A year on, pricing changes arrive about three times a quarter. Each one now edits a route, cannot be unit-tested without spinning up the web layer, and needs a manual regression pass: roughly three hours. Extracted behind a strategy, the same change is about half an hour.

That is the interest, and it is arithmetic, not opinion: 2.5 hours × 12 changes a year = 30 hours a year, around €2,400 of loaded engineering time, charged annually and rising as variants multiply. The extraction costs about six hours once. Payback lands in roughly ten weeks, so this loan should be repaid at the next pricing change rather than scheduled, discussed, or added to a backlog where it will lose to a feature every time.

The part worth noticing is that taking the loan was correct. At the time there was one pricing rule, the launch date was real, and the extraction would have been speculative structure for a case that had not appeared (lesson 0030). What separates engineering from drift is not refusing to borrow; it is that the entry named a trigger — "the third variant" — and the third variant is the thing that arrived.

Now the harder decision. A team of six keeps a ledger with fourteen entries, and can repay perhaps two this quarter. The instinct is to rank by ugliness, which is why most debt lists are sorted by how much they annoy the person who wrote them. A lead ranks by rate instead, and gets it from version control: how many commits touched each file in the last ninety days. Two entries turn out to sit in files touched forty and thirty-one times; four sit in files touched once. The four are not repaid, and saying so out loud is the point — they are not debt this quarter, and pretending otherwise would spend a quarter of the team's repayment budget on hours that were never going to be charged.

The alternative a lead rejects is the tidy policy: "we dedicate 20% of every sprint to technical debt". It sounds disciplined and it is untargeted — it funds repayment of principal in code with no interest, and it lets genuinely expensive debt survive because it was not this sprint's turn. Repayment is triggered by the change that makes the debt expensive, and the trigger belongs next to the code, not in a document nobody opens at the moment of the edit.

When this is the wrong move

Do not open a ledger entry for code with no future. Spikes, migration scripts, a promotional page with a fixed end date and anything you will delete before the next quarter charges no interest, and structuring it carefully is a cost with no matching return. Nor does the discipline pay before product-market fit: when the odds are good that the whole feature is deleted, the option value of shipping now exceeds the interest you would avoid.

And there is a repayment that is itself the wrong move: the one whose risk exceeds the interest. A rewrite of a critical path to remove an inconvenience you pay three hours a year for is not repayment; it is a new, larger loan taken to settle a small one — lesson 0037's irreversible class, entered voluntarily.

In the lab: the companion Phase 3 exercise closes the phase by having you write the debt ledger for the returns service you have been repairing — three entries with what was borrowed, what it charges, and the trigger — then rank them by how often version control says those files are touched.

Skill: name the loan

Practice: close the trade-off phase

Write the ledger for your own codebase's three largest invisible loans — each with borrowed / interest / repay-when lines. Then carry the largest one into lesson 0039: it is part of the constraint and risk context for the next initiative you lead.

Read and watch deeper

• "Technical Debt", Fowler — the loan metaphor, properly: principal, interest, and the decision to borrow.
• "Technical Debt Quadrant", Fowler — deliberate versus inadvertent, prudent versus reckless: the distinction between a loan and a mess.
• A Philosophy of Software Design, Ousterhout — ch. 2–3: the final statement that complexity is the enemy and working code isn't enough.
• "Simple Made Easy", Hickey — the closing keynote for everything this course taught.
• Watch: ArjanCodes YouTube — Arjan's own summary videos on software design; and the official sdm examples as living reference.
• Take your learning to the communities in Resources — trade-offs become judgment only in the wild.
• Reference: Trade-offs — short- vs long-term, and the three moves that run every trade-off in this phase.

Your agent-teacher remains available for any lesson — re-explanations, code reviews, or designing your next feature together. Ask anything.