Member-only story
Bring Your Own Examples
Embedding a Test Oracle in a Specification
A good specification should be readable at two levels. In the best specifications, these two levels are designed to be independent of each other.
The first level is meant for first time readers, and provides a linear explanation of what the specification is about without entering in too much details. After understanding it, the reader should be able to see how it fits in a larger design. It is generally made of informative parts, e.g., English text and examples.
The second level is meant to describe in unambiguous terms what a software developer needs to do to implement that specification. With that, software programmer should have enough information to work on an interoperable implementation. It is made of normative parts, e.g., English text, diagrams, and pseudo-code.
These two levels are generally not cleanly separated, as examples (which are informative) are generally interspersed within the normative text. Alas, it is a fact of life that software developers are less inclined to try to parse the English text when examples are also provided, increasing the risk of bugs when the examples are wrong. I explained in a previous article how I solved that problem for my specifications.
