Domain-Driven Design: Tackling Complexity in the Heart of Software

Written Design Documents
Spoken communication supplements the code's rigor and detail with meaning. But although talking
is critical to connecting everyone to the model, a group of any size will probably need the stability
and share-ability of some written documents. But making written documents that actually help the
team produce good software is a challenge.
Once a document takes on a persistent form, it often loses its connection with the flow of the
project. It is left behind by the evolution of the code, or by the evolution of the language of the
project.
Many approaches can work. A few specific documents will be suggested much later, in Part IV of
this book, which address particular needs, but I make no attempt to prescribe a set of documents
a project should use. Instead, I will offer two general guidelines for evaluating a document.
Documents Should Complement Code and Speech
Each Agile process has its own philosophy about documents. Extreme Programming advocates
using no extra design documents at all and letting the code speak for itself. Running code doesn't
lie, as any other document might. The behavior of running code is unambiguous.
Extreme Programming concentrates exclusively on the 
active
elements of a program and
executable tests. Even comments added to the code do not affect program behavior, so they
always fall out of sync with the active code and its driving model. External documents and
diagrams do not affect the behavior of the program, so they fall out of sync. On the other hand,
spoken communication and ephemeral diagrams on whiteboards do not linger to create confusion.
This dependence on the code as communication medium motivates developers to keep the code
clean and transparent.
But code as a design document does have its limits. It can over-whelm the reader with detail.
Although its behavior is unambiguous, that doesn't mean it is obvious. And the meaning behind a
behavior can be hard to convey. In other words, documenting exclusively through code has some
of the same basic problems as using comprehensive UML diagrams. Of course, massive spoken

---

communication within the team gives context and guidance around the code, but it is ephemeral
and localized. And developers are not the only people who need to understand the model.
A document shouldn't try to do what the code already does well
. The code already supplies the
detail. It is an exact specification of program behavior.
Other documents need to illuminate meaning, to give insight into large-scale structures, and to
focus attention on core elements. Documents can clarify design intent when the programming
language does not support a straightforward implementation of a concept. Written documents
should complement the code and the talking.