Pattern : CODE SAMPLES

CONTEXT : You are describing a solution to a software architecture or design problem. You have identified a Clear Target Audience that includes significant numbers of software designers and programmers.
PROBLEM : How can you make a software pattern sufficiently clear and unambiguous to facilitate straightforward implementation
FORCES :
- Software-related concepts are often complex and difficult to explain.
- Informal descriptive text is often unclear, and ambiguous.
- Programming languages are designed to convey software concepts in a formal, precise, and unambiguous manner.
- Many software workers are experienced and adept at reverse engineering concepts from software samples, and in fact prefer to learn ideas by looking at code.
- Many software patterns can be implemented in many different ways.
- Too much code interrupts the pattern's flow and may make it unmanageably large.
SOLUTION :
- Provide one or more implementation code samples, written in a prevalent programming language, to illustrate the pattern concepts.
- Use a programming language likely to be understood by the Target Audience. Choose an implementation approach that clearly demonstrates the essence of the pattern in a straightforward manner while minimizing unnecessary or distracting detail.
- Ensure that the code samples are well-commented and that all assumptions and design decisions are stated. Differentiate between aspects of the example that are essential to the pattern vs aspects that are arbitrary.
- Ensure that your code samples are "ready to run" (i.e. they are free from syntax errors and are complete). Syntax errors in code samples can be as distracting to people as they are to compilers.
RATIONALE : Well-commented example code is formal, precise, and unambiguous, and can be readily understood by many experienced software workers. Code examples provide concept reinforcement, providing a means for the reader to verify that they have understood the essential concepts of the pattern.