NAME: Running Example CATEGORY:
Pattern Language Structure
- CONTEXT: You are writing a pattern language that provides step
by step instruction on how to do or implement something.
- PROBLEM:How can you make it easier for the reader to
put a pattern language into practice?
- FORCES:
- The pattern should
be clear and complete so that reader can use it with
minimum effort or chance of mistake.
- The pattern should
be as concise as possible without being too terse for
most people to understand.
- Many people find
abstract descriptions very hard to understand.
- Examples are very
useful but must not take a lot of effort or prior
knowledge to understand.
- Any one example
may not be ideal for explaining a specific pattern.
- When a language contains a significant
number of patterns, each pattern must necessarily be more concise than a
free-standing pattern if only for reasons of overall pattern language size.
- SOLUTION:Try to use a single example in all patterns in the language. Explain it once, possibly in the
language
introduction. Use it to illustrate how each pattern in the language contributes to the solution. Use additional examples where the Running
Example does not illustrate the pattern effectively.
- RATIONALE: A single Running Example gives the reader more
insight into applying the whole pattern language than a bunch of individual examples. In effect, it is a case study. The reader does not
need to invest time and effort into understanding the example for each pattern; they pay this cost only once, when the example is
introduced.
- RUNNING EXAMPLE: Some code and executable generated by guikachu
