Component Design Patterns Format

Wiki favors a simpler format for patterns (see WikiMaster). Wiki also favors signatures over dialog labels. Think of wiki as well thought out (and edited) letters to the editor, not the transcript of a conversation. -- WardCunningham

Should the ComponentDesignPatterns be formatted using the AlexandrianForm? JoshuaKerievsky convinced me at ChiliPLoP'99 that it allows the reader to better capture the essence of the pattern, and that design pattern elements normally found in CanonicalForm and GoFform can be included without affecting it.

I've already converted LayeredFrameworks to AlexandrianForm. I think it fits the themes that are more decision-oriented in a better way than the others do.

Thoughts? And as Ward says above, its format might be more wiki friendly.

--PhilipEskelin

[ComponentDesignPatterns | ComponentDesignPatternsDiscussion]

Context

A paragraph-based description of a situation you might be in when the pattern might apply to a problem you are trying to solve.

An Applicability section might be added that describes a list of bullet points that qualify or disqualify the use of the pattern in your context.

Problem

Posed as a question.

Forces

A bulletted list of forces that describe the conflicts inside the problem.

Solution

Possibly in terms of other patterns, see ContextIndependence.

Solution can also have Participants, Structure, and Collaborations sections if it helps convey the theme to the reader. More design-like patterns will probably delve into this level of detail.

Resulting Context

Including new problems to be solved and the patterns that can solve them.

Here, Benefits/Liabilities can be covered in a Consequences section if this amount of detail is important for the pattern in question.

Known Uses

Sometimes a part of Example depending on the type of pattern. The RuleOfThree should govern that at least three known uses exist for the pattern, and as many as necessary should be written in this section to help the reader relate to it.

Example

More detailed than Known Uses, can include code and/or diagrams. Especially for pattern at the design level -- many times source code can help the reader understand a specific implementation instance that can result from the pattern.

Implementation and Sample Code sections can be outlined in Example for more design-like patterns.

Related Patterns

Compare and contrast to other patterns, rather than lead the reader on to solve problems in the resulting context.

Discussion

Discussion takes place after horizontal rule (e.g., as below). Sometimes discussion has taken place elsewhere (e.g., ComponentDesignPatternsDiscussion) and is consolidated into the pattern's discussion. Other times, as the pattern is being constructed, discussion intertwined in the pattern is moved below.

NatPryce: I've been thinking about this some more. I agree that higher level patterns don't really fit into the GoFform very comfortably; the CoplienForm seems more natural. This is especially true, IMHO, for process patterns such as CookbookApproach and CautiousBuyOverBuild.

However, I don't think that there is a cut-off point at which the pattern language stops being high-level and suddenly becomes low-level, and I think the sudden change of pattern format would disturb the "flow" of the pattern language. Therefore, I'd prefer to see all the patterns in a Coplien-like format, along the lines of: (see pattern format above -ed)

What do people think? I know it's only a stylistic issue and not the most important at the moment. However, if you're up for it I don't mind refactoring some of the pages.

BradAppleton: Some folks use a little bit of both. See CanonicalForm for a description of how each maps "roughly" to the other (see also PatternForms). --

PhilipEskelin: I like CanonicalForm in its simple form for more design-centric patterns (e.g., ContainerManagedPersistence or ConnectionSingleton). The expanded form specified by BradAppleton can be used for the higher-level patterns.

Does anybody care that I wrote the prototype for this [DistributionOfComponents] in CoplienForm? I think it fit the scope of the pattern better. Perhaps we can use the CoplienForm for our higher-level patterns and leave the more design-heavy ones in GoFform.

NatPryce: I prefer the CoplienForm to the GoFform for both high level patterns and low level design patterns. CoplienForm leads the reader forward from their problem to a (partial) solution and then further on to patterns that solve the resultant problems. I think that this is part of what is meant by "generative" patterns. I feel that the GoFform acts in reverse -- it gives a more explanatory feel to the pattern.

PhilipEskelin: Perhaps this will allow us to escape the sardonic state of Intent and Motivation -- as pointed out by Ralph -- in our LayeredFrameworks ProtoPattern ;-)

PhilipEskelin: I moved Known Uses above Example since it's more of a summary. That way, the reading going from top to bottom reads the big picture first, then sees a specific example. Finally, Related Patterns being last allows the reader -- after gaining an understanding regarding its intent -- to analyze its relationship with other existing work both inside and outside the language.

NatPryce: Much better!

NatPryce: I find some of the discussions quite hard to read when the participants are writing large pieces of text and signing them at the bottom. What do you think of a dialogue style similar to plays or screenplays, where each part of the discussion starts with the writers name, followed by a colon (as does this suggestion)?

PhilipEskelin: Nat, I'm game . . . I feel the same way, but was too lazy to come up with a better idea. Let's try it and see if it catches on. It helps especially in areas like this one where multiple people discuss something between the horizontal rules. I'll need to get used to not putting my name at the end, however (NullName?) ;-)

NatPryce: in long discussions, it is helpful to make the names of the "speakers" bold, as done with this sentence.

Here is a template that can be copied before editing/creating other patterns (edit out the detail sections if it's a higher-level pattern that doesn't require them):

[ComponentDesignPatterns | CategoryPattern]

Context

Applicability

Problem

Forces

Solution

Participants

Structure

Collaborations

Resulting Context

Consequences

Known Uses

Example

Implementation

Sample Code

Related Patterns

JoshuaKerievsky: Fellows, listen, it is time to drop the various pattern forms and realize that Alexander and company had a very good form, that utterly blows away the forms our community has decided to create. If you don't believe what I'm saying, send me three consecutive patterns from your language, and I'll rewrite them to prove my point. I recently did this with three of Cope's Org patterns, and many who have seen this, including Cope, agree that the rewritten patterns work better because of the Alexandrian form.

PhilipEskelin: Joshua, you definitely convinced me at ChiliPlop that this is the way to go. So far I've converted one pattern, LayeredFrameworks, to AlexandrianForm. As I have time to convert more of them, I wonder how well this format will bring out structure, collaborations, etc. in design patterns. My plan is to put these sections into the problem/solution area as illustration elements that help deliver the pattern-in-question's essence.

What do other folks think about ComponentDesignPatternsFormat being in the AlexandrianForm?

NatPryce: Go for it!