The rest of this page discusses a particular CanonicalForm
for design patterns.
, in general, is really a special member of a set of equivalent elements. For example, disjunctive normal form is a CanonicalForm
in the propositional calculus where a proposition is represented as the disjunction (logical 'or') of a set of propositions which are not themselves disjunctions. (Mathematicians please feel free to correct this half-remembered definition!) They are frequently useful in software to speed comparisons and lookups.
To my knowledge, CanonicalForm
is identical to AGCSform and CoplienForm
. See also: http://www.hillside.net/patterns/writing/writingpatterns.htm
Some people use CanonicalForm
to refer to AlexandrianForm
, but canonical
form doesn't necessarily mean the original form, it means the simplest, most basic or primordial form. For example a "canonical matrix" is one with 1's along the primary diagonal and zeros everywhere else. A "canonical basis" is a set of vectors basically from a canonical matrix. Canonical SOP and POS forms in digital logic refer to the minimal & basic algebraic sum of products (SOP) or product of sums (POS).
I think the CanonicalForm
for a pattern is therefore the form that explicitly spells out the most basic elements: name, context, problem, forces, solution, etc. That is also how I most often see it used. The AlexandrianForm
is much more advanced than this because it manages to provide "coverage" of these essentials while maintaining the flow of straight prose (which is no mean feat).
So the "canonical" form for describing a pattern uses sections with the following headings:
- Alias (optional)
- Example (optional?)
- Resulting Context
- Rationale (optional)
- Known Uses
- Related Patterns
Most people put the "Problem" section *before* the "Context" section. I have become rather fond of swapping the order of these two, letting the "Context" set the stage for the statement of the "Problem".
Why the "optional" after Example? Does it mean that you don't need an example at all, or just that you needn't state it?
- It means the example may be optional as a separate section in its own right. In many cases, the Solution and/or Implementation section will implicitly use an example (often one described by the Motivation section if GoF format is used). Also, sometimes Known Uses are used as examples, but still remain in the Known Uses section. That's what I prefer, if possible, so the example shows not just some fictitious toy scenario, but comes from the real world. This cant always be done in the the limited space provided ;-).
The GoV POSA book uses something very similar to CanonicalForm
. Basically it uses the same format but also add a section entitled "Variants" to describe variations of the pattern.
maps roughly to GoFform
in the following manner:
CanonicalForm ==> GoFform
Alias Also Known As
Example Sample Code
Resulting Context Consequences
Known Uses Known Uses
Related Patterns Related Patterns
Ive seen some people use a combination of both, where CanonicalForm
at the high-level sections and GoFform
is used for some of the subsections and
a select few of the higher-level sections. So it might look like:
- Pattern Name
- Aliases (Also Known As)
- Resulting Context (also "Resolution of Forces")
- Rationale [if needed]
- Sample Code
- Known Uses (sometimes this is part of Examples, or vice-versa)
- Related Patterns
One rarely uses all
the subsections for every pattern, just when the extra level of detail seems warranted. Personally, I like to see the Context precede the Problem because I think it sets the stage for understanding the problem statement.
Brad, I like the variation you present above. We started doing them in the GoFform
, then switched over to something resembling CanonicalForm
. We didn't want to keep both, since it might confuse the reader or promote a discrimination between some patterns more at the architecture level and those at the design level. By having subsections like the ones above where warranted, then, elaboration upon more design, consequences, and implementation is done only where it adds value to the reader. -- PhilipEskelin
Gush! -- BradAppleton
And now, based on a form which originated from KentBeck
, and heard of by myself during PlopConference
this year, there is a CompactForm
that hopes to make pattern languages easier to write, understand, and read. I hope I got it right. ;-) -- PhilipEskelin
I offer a trivial example of CanonicalForm
. -- KarlKnechtel