Building Software

Engineering Fundamentals for the Agent Era

Contents Section 6, Design

Managing Complexity

Mistakes to catch in review

  1. A factory, an interface and a configuration loader added for a feature that has exactly one implementation.

  2. The same tax-rounding rule copied into three files, so a later fix lands in only one of them.

  3. A catch-all utilities module that everything imports, coupling unrelated parts of the system.

  4. A helper named processData that validates and saves in one call, so a caller that only wanted validation writes to the database.

Coupling, cohesion, information hiding and simplicity: the principles that decide whether a codebase gets easier or harder to change over time.

Topics

Essential and Accidental Complexity
Separating the difficulty that comes from the problem from the difficulty added while solving it, and technical debt as the accidental complexity that was kept on purpose, with the interest it charges on every later change.
Coupling and Cohesion
Keeping related things together and unrelated things apart, so changes stay local.
Information Hiding and Deep Modules
Small interfaces over substantial functionality, so callers never depend on internal decisions.
Naming
Names that say what something does, which make code checkable by reading and easier for models to use correctly.
Simplicity and YAGNI
Building for the requirements you have, and adding generality only when a second real case appears.
Refactoring Under Tests
Changing structure in small steps without changing behavior, with tests proving each step.

You understand it when you can

  • Identify the most tightly coupled module in a codebase and explain which changes it makes hard.
  • Refactor duplicated logic into one place and show with tests that behavior did not change.
  • Explain when duplication is cheaper than the wrong abstraction.

Drill

An agent implemented a discount feature by adding a DiscountStrategyFactory, a DiscountProvider interface and a config loader, each with a single implementation, and copied the tax-rounding rule into two new files. Find what can be deleted without changing behavior, and where the copied rule will eventually disagree with the original.

Start here

Watch

Read

A Philosophy of Software Design

John Ousterhout, 2021, 2nd edition.

Short chapters on deep versus shallow modules, information leakage, pulling complexity downward and choosing names give a reviewer a vocabulary for spotting over-layered agent code.

Refactoring: Improving the Design of Existing Code

Martin Fowler, 2018, 2nd edition.

The catalog of behavior-preserving transformations (Extract Function, Inline Class, Remove Middle Man) and the discipline of running tests after each step are exactly what deleting a one-implementation factory safely requires.

Tidy First?: A Personal Exercise in Empirical Software Design

Kent Beck, 2023.

A short book that treats coupling and cohesion as economic decisions and explains when to tidy structure before, after, or never relative to a behavior change.

Primary sources