Canonical Form

The rest of this page discusses a particular CanonicalForm for design patterns.

A CanonicalForm, 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:

Name
Alias (optional)
Problem
Context
Forces
Solution
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.

CanonicalForm maps roughly to GoFform in the following manner:

  CanonicalForm       ==>   GoFform
  =================         ===============
   Name                      Name
   Alias                     Also Known As
   Problem                   Intent
   Context                   Applicability
   Forces                    Motivation
   Solution                  Participants,
                             Structure,
                             Collaborations,
                             Implementation
   Example                   Sample Code
   Resulting Context         Consequences
   Rationale                 ???
   Known Uses                Known Uses
   Related Patterns          Related Patterns

Ive seen some people use a combination of both, where CanonicalForm is used 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)
Intent
Problem
- Motivation
Context
- Applicability
Forces
Solution
- Participants
- Structure
- Collaborations
Resulting Context (also "Resolution of Forces")
- Benefits
- Consequences
Rationale [if needed]
Examples
- Implementation
- 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.

-- BradAppleton

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 at OrcKillingPattern. -- KarlKnechtel

CategoryPattern | CategoryPatternForm