# 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.