Code and API Design

Architecture is the shape of the system at a distance. Design is the shape up close — how classes, modules, and interfaces are structured so the code stays changeable. The same theme from earlier chapters applies here at a smaller scale: it's all about managing coupling and cohesion. But code-level design has a distinctive trap that's worth naming up front: the failure mode here is as often too much structure as too little. Premature abstraction and pattern-cargo-culting cause as much damage as having no structure at all.

SOLID, held lightly

SOLID is five principles for object-oriented design. They're genuinely useful as lenses, dangerous as commandments. Briefly:

• S — Single Responsibility. A module should have one reason to change. (The cohesion idea from Chapter 2.)
• O — Open/Closed. Open for extension, closed for modification — you should be able to add behavior without editing existing, tested code.
• L — Liskov Substitution. A subtype should be usable anywhere its parent type is, without surprises. If your Square extends Rectangle breaks code that worked on Rectangle, the inheritance is lying.
• I — Interface Segregation. Many small, focused interfaces beat one fat one; clients shouldn't depend on methods they don't use.
• D — Dependency Inversion. Depend on abstractions, not concrete implementations — so high-level policy doesn't break when low-level details change, and you can swap implementations (real database for a fake one in tests).

The honest framing for a lead: SOLID describes properties that well-factored code tends to have. It does not mean "add an interface and a factory for everything." Applied dogmatically, it produces a maze of indirection where you open six files to follow one operation. Use the principles to diagnose code that's painful to change ("this is hard to test → maybe we're not inverting dependencies"), not as a checklist to apply preemptively.

Design patterns without the cargo cult

Design patterns are named solutions to recurring design problems — Strategy, Observer, Factory, Adapter, and so on. Knowing them is valuable for two reasons: they're genuinely good solutions, and they give your team a shared vocabulary ("let's make this a strategy" communicates a whole design in three words).

The trap is using patterns as a sign of sophistication rather than a response to a real problem. A codebase where every simple thing is wrapped in a factory producing a strategy injected by a builder is not sophisticated; it's a junior engineer who just read the patterns book. The mature instinct: reach for a pattern when you feel the specific pain it solves, not before. Most code needs far fewer patterns than pattern enthusiasts apply.

The timing of abstraction

This deserves emphasis because getting it wrong is so common. An abstraction has a cost (indirection, a thing to understand) and a benefit (it absorbs change in one place). The benefit only materializes when change actually arrives in the shape you predicted.

The two opposing mistakes:

A practical heuristic: prefer duplication until the pattern is clear. The "rule of three" is a decent guide — by the third time you write something similar, you understand the real shape of the variation well enough to abstract it correctly. Abstracting after the first occurrence is guessing; abstracting after the third is responding to evidence. As the saying goes, a wrong abstraction is more expensive than a little duplication — because duplication is easy to see and consolidate later, while a wrong abstraction forces everything through a shape that doesn't fit.

API and contract design

For a lead, this is the highest-stakes part of code-level design, because APIs are where teams and services integrate — they're the contracts that, once published, are expensive to change. A bad internal function is a private problem; a bad public API contract is everyone's problem, possibly for years.

Principles that matter:

Design the contract, not the implementation. A good API exposes what a caller can do and hides how it's done. Callers should be able to depend on the contract while you freely change everything behind it. Leaking implementation details into the interface (exposing your database column names as API fields, say) recouples consumers to your internals.

Make contracts hard to misuse. Clear names, explicit required vs optional fields, sensible defaults, and errors that tell the caller what to do. The best APIs make the right thing easy and the wrong thing difficult or impossible.

Plan for change with versioning and backward compatibility. You will need to evolve an API after others depend on it. The discipline: additive changes are safe (new optional fields, new endpoints); removing or changing the meaning of existing fields is breaking and needs a version strategy and a migration path. A useful mental model is Postel's robustness principle — be conservative in what you send, liberal in what you accept — though apply it thoughtfully, since being too liberal in what you accept can mask integration bugs.

flowchart LR
  C[Consumers] -->|depend only on| Contract[/Stable API contract/]
  Contract --- Impl[Implementation:<br/>free to change behind contract]
  Contract -.->|additive change:<br/>safe| V2[New optional field]
  Contract -.->|breaking change:<br/>needs versioning| Vx[Removed/renamed field]

Think about the consumer's experience. The best test of an API is to write the client code first, before the implementation — you immediately feel the awkwardness of a bad design when you're the one calling it.

What this means for you as a lead

In code review, watch for both failure modes. When you see indirection that isn't paying for itself — abstractions with a single implementation, patterns applied to problems that don't have them — gently ask "what variation is this absorbing?" When you see the same logic copied a third time, that's the moment to consolidate. And spend disproportionate care on API contracts: they're the cheapest thing to get right early and among the most expensive to fix once others depend on them. A reviewable rule of thumb — if this were published and a hundred teams depended on it, would we still be comfortable? — calibrates how much rigor a given interface deserves.