Example-driven development: bridging tests and documentation

TL;DR

This paper introduces Example-Driven Development (EDD), which enhances testing and documentation by using live, inspectable examples that improve system explainability and integration.

Contribution

It proposes a novel approach that combines testing and documentation through examples, enriching TDD with live programming and embedding explanations directly into documentation.

Findings

Examples are causally connected to code and reusable.

Examples can be embedded into live documentation.

EDD enriches TDD with live, inspectable examples.

Abstract

Software systems should be explainable, that is, they should help us to answer questions while exploring, developing or using them. Textual documentation is a very weak form of explanation, since it is not causally connected to the code, so easily gets out of date. Tests, on the other hand, are causally connected to code, but they are also a weak form of explanation. Although some tests encode interesting scenarios that answer certain questions about how the system works, most tests don't make interesting reading. Examples are tests that are also factories for interesting system entities. Instead of simply succeeding or failing, an example returns the object under test so that it can be inspected, or reused to compose further tests. An example is causally connected to the system, is always live and tested, and can be embedded into live documentation. Although technically examples constitute just a small change to the way that to test methods work, their impact is potentially ground-breaking. We show (i) how Example-Driven Development (EDD) enriches TDD with live programming, (ii) how examples can be molded with tiny tools to answer analysis questions, and (iii) how examples can be embedded within live documentation to make a system explainable.