Canonical Form

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.

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

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 ;-).

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

• 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

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

CategoryPattern | CategoryPatternForm

This page mirrored in WikiPagesAboutWhatArePatterns as of April 29, 2006