The toy example as a specification device
Agile methodologies are pervasive in today’s development culture. The ideas are used not only in software development but in other domains as far from software as sales. However, when we develop model-based tools, we are usually faced with the challenge to develop a DSL, or several in small iterations. This creates several challenges, but today I am going to be focusing on the specification of the requirements. Agile methodologies require to implement the software in small iterations where I think that one of the best ways of specifying part of a feature in a complex model-based engineering tool is through a toy example. Let me explain why.
What is a Toy Example?
Toy examples are the equivalent of dummy data for tool developers. It is a model that uses the features of your tool, the constructs of your custom domain-specific language and the diagrams that you provide in your tool. A good toy example, in my opinion, can capture the requirements in a way that both developer and subject matter expert understand well. The subject matter expert can understand that from the simple primitives shown in the toy example, the user can build more complex and expressive models. The developer on the other hand has a solid understanding of what needs to be included in the feature
The Characteristics of a Good Toy Example
A good toy example can accelerate the development and act as a bridge between the tool developer and the subject matter expert. Here are some characteristics that I think need to be included in a toy example to make it as good as possible
Completeness
A good toy example is complete. I’ve seen a lot of specifications where the specification is just a part of the diagram or a construct of the language. This works only for the simplest features or modifications, but for whole features, it can cause problems later, and problems mean having to rewrite the code or having testing defects later.
Simple, Small & Standalone
A good toy example is extremely simple and follows the aphorism:
Everything should be made as simple as possible, but not simpler.
Simplicity entails that is has as few parts as possible, ideally just one, and the relationships with other parts are kept to a minimum. Each part should be as small as possible, so that it can be understood with just one glance. Finally, a toy example should ideally be standalone. This reduces complexity by removing relationships to other components.
It is easily understandable for a non-domain expert
This might be the hardest thing to achieve and may sometimes be difficult or even impossible, but it is worth striving for it. Indeed, having an example that can be easily grasped by a domain expert can help the development team a lot. This is specially useful for the development team to understand not only the task at hand but also the implications. An ideal toy example is easily extensible to test for corner cases and serves as the basis for later development efforts.
Beyond the Toy Example
The toy example is great but it is not enough. My opinion is that toy examples are ideal for starting the development of a feature. They should give the general feeling of the feature, for both the developer and the subject matter experts that will later use the tools. After the feature is clear, corner cases need to be handled. My personal choice for corner cases are unit tests, they are usually fast to execute, to create, and can be based on toy examples.