liveBook · Manning

Accidental complexity

As explained in Clean Applications with Hexagonal Architecture

The additional difficulty and disorder introduced by design choices, implementation shortcuts, and unnecessary coupling rather than by the problem domain itself.

Accidental complexity is the extra difficulty and disorder introduced by design choices, shortcuts, and brittle abstractions—not by the problem itself. It appears when a simple change spreads across files or unrelated tests break. section 1.0

Hard-wiring lets changes ripple between parts of a system:

  • Framework, database, interface, and service dependencies become coupled to the application. section 1.0
  • Database choices leak into business logic, transport models become domain models, and local shortcuts constrain other components. section 1.0

Hexagonal Architecture contains these ripple effects with explicit boundaries: the core defines what it needs, while replaceable adapters connect external technologies. Dependencies point inward, keeping domain logic framework-agnostic and testable in isolation. section 1.0 section 1.6

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Defines the problem, traces coupling to concrete maintenance failures, and connects explicit boundaries to isolation.
Examples
Uses changes that touch many files, mysterious test failures, database leakage into business logic, and transport models used as domain models.
What you can do after
Apply Ports and Adapters to isolate business logic and make external technology replaceable at system boundaries.
How it connects
Connects accidental complexity to Hexagonal Architecture, Ports and Adapters, and the Dependency Inversion Principle.

Also explained in

Compare how 2 books explain accidental complexity →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.