Member-only story
Embedding an Examples Generator in Specifications
Generating all examples
It is established that when confronted to a plain English text that describes something and examples of the same thing, developers tends to build their understanding from the examples and ignore the explanations. This is fine until the examples are incorrect, which happens more often than people think.
The correct way to use examples in a specification is to use them to validate what was learnt by reading the text surrounding it, which does not work if the reader is focused only on these examples. A first line of defense against that problem is to generate the handful of static examples from an underlying formal specification, making it less likely that the text and the examples tell a different story.
But if the goal is really to help the readers validate their understanding of the text, there is no reasons to limit the examples to a small selection. The next step in helping the readers is to let them provide what they think are good and bad examples, and have a piece of code in the specification validating that for them. I call that dynamic examples and that uses something called a test oracle.
It is possible to have both static and dynamic examples in a specification, but an even better idea is to replace the static examples with another…
