Discussion of Pattern Form [ sd&m Home | ARCUS HomeWhat's New | | Contact] |

This page contains our current agreement on Pattern Form. It reflects the experiences made with about 30 Patterns we have written. Some of them have been reviewed at EuroPLoP and PLoP. We have experimented with GOF-Form and the Style from the POF-Book (Party of Five, vulgo Buschmann et al.). Our current direction is to:

• emphasize Forces and Consequences,
• try to tell a good story that sells Patterns to the respective reader.
• Confine rambling to certain areas of a Pattern and be short and concise in most sections

On this page we have summarized the form and added some review reminders that we have picked up at PLoPs and from the shepherding process

Pattern Form

Name

• One to three words should say all.

Also Known As

• Pointer to other descriptions of the same pattern and other names for the same pattern

Abstract

• goal: attract the reader.
• should be around 3 lines

At this point the reader should have an idea what the pattern is about and whether it's worth reading.

[ Example ]

• should provide the reader with a story and make up a context for the pattern
• around a half page
• best enriched with a picture
• style is "story telling"
• some rambling allowed

Context

• should be around 3 lines
• should summarize the context given by the example or give a short description of the design situation in case no example is necessary.

Problem

• one short sentence.
• Question that summarizes the design problem to be solved.
• good style would be "How do you .... ?"

Forces

• lists factors that influence a solution (for an explanation refer to Alexander - we're not in philosophy here).
• bulleted list, short items describe the text to follow.
• A form "Force X versus Force Y" can avoid a lot of redundancy for most time the arguments against Force X are the arguments that are in favour of counterforce Y.
• one paragraph per force or pair of forces.
• short sentences.

At this point the reader should agree that there is a problem to be solved and be given an idea of the forces that influence a solution

Solution

• idea in 3 lines maximum.
• the essence, short and concise.
• should answer the question posed by the problem.

Structure

• OMT diagram (only if non-trivial) plus some explanation
• should be abstract - see GOF-book for good examples

Participants

• oriented along roles and responsibilities. We do not want the graphics of CRC cards but we like the idea of describing what the objects are responsible for and what roles they play
• one heading for each participant (class or component)
• points in a bulleted list
• we don't like this part too much but we don't like the long sermons in the POF book as well. The GOF book is a bit short - POF is a bit too long. So we'll stick to GOF until we have some better ideas

Dynamic Behavior

• POF style object interaction diagrams
• must be explained by accompanying text
• as many scenarios as necessary to make the solution understandable
• should refer to the abstract concepts in the Structure Section - not to concrete classes in the example section

[ Example Resolved ]

• free style description of how to aplly the solution to the above Example (as described in the Example Section)
• Use code, OMT diagrams or object interaction diagrams plus text
• make it short

Consequences

• form should follow the Forces Section
• the order, in which consequences are presented,should follow the Forces Section
• Don't forget negative consequences
• add something on applicability like "don't use this pattern if ...." or "positively use this pattern if"

At this point the story is completed - the following sections help the reader to implement the pattern and assist in implementing it

Implementation

• Enumerates points the implementor has to think of when applying the pattern
• bulleted list with Items
• one paragraph per item

[ Sample Code ]

• provides a sketch of the solution for better understanding
• should be best compiler proofed, running code
• not a specification but an illustration
• some more code than the excerpts shown should be available on demand

[ Variants ]

• running text describing major variants of the pattern
• best one paragraph per variant
• bet no bullets as too many bullets impair readability

[ Related Patterns ]

• should not be redundant. If a pattern is referenced in the implementation section or the structure it should not again be referenced in Related Patterns. Redundancy scares off readers
• should explain why this pattern is not identical to another one like "this pattern is not a Bridge because...." or this pattern may be used as an alternative for X because ...."
• not a Section to show off one's expertise in patterns. No name dropping please.

Known Uses

• the goal are three well known, independent known uses in published design like MacApp, ET++ and VisualSomething.
• as this is not always feasible in sd&m projects, we are content with project references.
• The known uses section should contain some information on where the patterns has been applied in a design and which concepts of the pattern have been applied to which part of the Known Use.

Further Reading

• should provide links to information that is too bulky to be presented in the pattern itself
• Should give links to general concepts or literature that contains further details that are necessary to implement the pattern
• Freestyle
• No name dropping, redundancy or affluent self citations please.

Aknowledgments

• Tom Peters says: "don't forget your thank you notes" and "give credit". As paterns are mined from other peoples solutions and improved with other peoples help we should give the

We dropped the following GOF elements:

• Intent: We call it Abstract as an Intent is very hard to write and may take longer than the paper
• Motivation: Split into Example, Problem, Context and Forces
• Applicabilty: See the Consequences Section

Review Reminders

• Is the pattern one pattern or is it better to split it up?
• Does the story sell the pattern?
• Did the author adhere to journalist economy?
• Are there negative consequences?
• Do forces read like requirements?
• Do forces match consequences?
• Does the Pattern cope with standard forces like
  • Performance
  • Space
  • Complexity
  • Maintenance
  • Flexibility
  • Testability
  • (list to be continued)