Abstract: The documentation for a framework must meet several requirements. These requirements can all be met by structuring the documentation as a set of patterns, sometimes called a "pattern language". Patterns can describe the purpose of a framework, can let application programmers use a fmework without having to understand in detail how it works, and can teach many of the design details embodied in the frame work. This paper shows how to use patterns to document a framework, and includes a set ofpatterns forHotDmw as an example. Christopher Alexander, an architect, developed the idea of a "pattern language" to enable people to design their own homes and communities [Alexander et. al.]. A pattern language is a set of patterns, each of which describes how to solve a particular kind of problem. His pattern language starts at a very large scale, explaining how the world should be broken into nations and nations into smaller regions, and goes on to explain how to arrange roads, parking, shopping, places to work, homes, and places of worship. The patterns focus on finer and finer levels of detail, passing though a discussion of how to arrange rooms in a house, and finally describing the type of material to use for walls, how to decorate rooms, and how to provide lighting. Alexander's pattern language is supposed to be a document that non-architects can use to design their own communities and homes. No specialized training is needed to use it. It focuses on common design problems that non-architects will encounter, like how to build bedrooms and row houses, rather than uncommon ones, like how to build concert halls and cathedrals. Although Alexander uses the term "pattern language" to describe his document, it is not a formal language like a context-free language, for example. A pattern language is a structured essay, not a mathematical object. Therefore, we will replace that term with the term "patterns". A framework is a reusable design of a program or a part of a program expressed as a set of classes [Deutsch] [Johnson and Foote]. Like all software, it is a mixture of the concrete and the abstract. Since frameworks are reusable designs, not just code, they are more abstract than most software, which makes documenting them difficult. Frameworks are designed by experts in a particular domain and then used by non-experts. The principal audience of fmmework documentation is someone who wants to use the framework to solve typical problems, not someone building a software cathedral. Patterns seem to be well suited for this audience. This paper shows one way to document frameworks with patterns. It is essentially an experiment to see how well patterns work to describe a framework. The result is a set of patterns that are included in the appendix. The main purpose of a set of patterns is to show how to use a framework, not to show how it works, but patterns can also describe a great deal of the theory of its design. One of the important features of Alexander's pattern language is its structure; each pattern is written in a particular format and patterns are arranged so that each pattern leads into the next. The format that Alexander uses is unlikely to be suitable for software. For example, since he is building physical objects, he requires pictures both for stating the problem that a pattern solves and for stating the solution. Thus, the patterns in this paper have a different format that the one he used. OOPSLA '92, pp. m-i(i 63 Each pattern describes a problem that occurs over and over again in the problem domain of the framework, and then describes how to solve that problem. Each pattern has the same format. The format used in this paper is to first give a description of the problem in italics. This is followed by a detailed discussion of the different ways to solve the problem, with examples and pointers to other parts of the framework. The pattern ends with a summary of the solution, again in italics, followed by pointers to other patterns that are needed to fill it out and embellish it. The appendix to this paper describes a set of ten patterns for HotDraw, a drawing framework. For example, pattern 4 is It has a bounding box that is independent of the bounding box of its components, and it will display its components only if they are inside of its bounding box. The selection tool and text tool will operation on its components when the left shift key is pressed. Custom tools can operate directly on the components, if you want. . . . To enforce constraints between the components of a complex figure, see Constraints (5). This pattern assumes that the reader has read other patterns. In this case, pattern 4 is preceded by pattern 2, which defines figures and bounding boxes. It also depends on pattern 1 to introduce the PERT chart example. Patterns are problem-oriented, not solutionoriented. Each pattern describes how to solve a small part of the larger design problem. Sometimes the solution is to make a new subclass (e.g. pattern 2), sometimes it is to parameterize an object of an existing class (e.g. patterns lo), and sometimes it requires connecting several objects together (e.g. pattern 3). Fmmework documentation for a framework has three purposes, and patterns can help fulfill each of them. Documentation must describe l the purpose of the framework l how to use the framework l the detailed design of the framework. Patterns are best suited for teaching how to use a framework, but we will see that with care, a set of patterns can meet all three of these purposes for framework documentation. A framework is a reusable design for solutions to problems in some particular problem domain. The purpose of the framework, i.e. the problem domain for which it is designed, must be the first thing that the documentation describes. If the framework turns out to be inappropriate then the reader does not have to continue reading. The first section should be small, so that every potential reader will have time to read it. It is not unreason-able to expect that an experienced designer will have read the first section of the documentation for every framework owned by his or her organization and so know the purpose of each one. This will reduce the problem of finding the right software to reuse. Each pattern describes the problems it is meant to solve. The first pattern for a framework describes its application domain. It does this by giving examples, as do other ways of documenting frameworks. In addition, the first pattern introduces the rest of the patterns in the language, and it will usually tell which patterns should be 64 read next. Thus, it acts both as a catalog entry for the framework and as a road map. Next, the documentation for a framework should show how to use it to build applications. Most users of a framework want to know as little as possible about the framework. This means that they are not interested in a description of the design of the framework, but want a kind of cookbook, giving detailed instructions for using the framework. This is similar to the minimalist instruction of Caroll[Caroll] [Rosson et. al.], which tries to show how to solve particular problems and make a system useful to a user as soon as possible. for frameworks describes how the framework works first, and then describes how to use it. However, part of the folklore of frameworks is that nobody understands a framework until they have used it, so using it is more important than reading about the theory behind it. In fact, I believe that theory should follow practice, that a discussion of the theory behind a framework is only understandable once the framework itself is understood, and that the best way to get a general understanding of a framework is to use it. Thus, we need to explain how to use a framework without explaining how it works. This is not a new idea; the documentation for MacApp has long contained a cookbook [Apple] and the first documentation for Model-ViewController (MVC) was called a "Cookbook for Model-View-Controller" [Krasner and Pope]. Patterns are more like the MacApp cookbook than the MVC cookbook. The MCV cookbook is a collection of examples, but is still a tutorial designed to be read as a unit. The MacApp cookbook is a collection of "recipes" with some cross references, where each recipe solves a particular problem like how to drag an object. It does not make use of structure as much as the set of patterns for HotDraw. None of these documents is as deterministic as a typical cookbook, which gives algorithms for making dishes, not just hints or rules of thumb. The third purpose of documentation for a framework is to describe its design. This not only includes the different classes in the framework, but also the way that instances of these classes collabo-rate. Although programmers can usually interconnect objects without completely understanding how they work, and can even make subclasses following a cookbook, a framework is most useful to someone who understands it in detail. The major weakness of cookbooks is that they describe the typical way that the framework will be used. A good framework will be used in ways that its designers never conceived. Thus, a cookbook is insufficient to describe every use of the frame-work. This is probably why the MVC cookbook also includes an informal description of the design of the framework, as well as instructions on how to use it[ Krasner and Pope]. On the other hand, someone's first use of a framework usually fits the -stereotype of the framework's designer, and using a framework helps provide the intuition needed to read a more formal specification. In contrast to formal specifications like contracts [Helm et. al.], patterns are an informal technique aimed primarily at describing how to use a framework, not describing its algorithms, patterns of collaboration, or shared invariants. However, patterns provide many opportunities for describing a design, and it is possible to include much of the design of a framework in patterns for it. The section between the statement of the problem to be solved and the summary of the solution elaborates upon the solution and explains why it works. This section usually describes part of the design of a framework. If the patterns are designed carefully then they can also describe the design of a framework. Where should design information be placed in a set of patterns ? In general, detailed design information should be hidden as long as possible from the reader, because most readers are not interested in seeing it. On the other hand, it is necessary to make sure that the patterns contain the information somewhere and that the information is not duplicated. The technique that I used was to treat the set of patterns as a directed graph, using the references from one pattern to another as the edges, and to place design information as far from the first pattern as was feasible. Some design 65 information, such as the fact that a HotDraw application is made up of Figures, Drawings, Handles, and Tools, must be described in the very first pattern, but most of it can be moved to subsequent patterns without using forward references. Examples play a key role in the documentation of frameworks. The Examples make frameworks more concrete, make it easier to understand the flow of control, and help the reader to determine whether he or she understands the rest of the documentation. Examples are also important in documentation based on patterns. Both the problem that a pattern is supposed to solve and its solution are often described in terms of examples. This is most obvious when describing the initial pattern, the one that describes the purpose of the framework. It is usually hard to specify a problem domain precisely, but a small set of examples usually makes the general area clear. These examples are not intended to show how to use the framework to build applications, nor to explain the design of the framework, but rather to show what the framework is good for. Thus, the examples for a user interface framework will be finished user interfaces, while the examples for a compiler framework will be finished compilers. The examples will point out user-level features that the framework provides, but they will not explain how these features are provided or how the application designer uses them. Examples can also be used to show features of the design. The patterns for HotDraw use examples to motivate the need for complex figures (pattern 4) and for constraints (pattern 5). These patterns start with example applications of HotDraw and finish with a discussion of the code needed to implement these applications. Examples can be used to test drive the,pattems. The examples should exercise all the patterns, so someone can make sure that they learn all the patterns by trying out all the examples. The examples that have been used to describe the purpose of HotDraw (i.e. the examples in the first pattern) are sufficient to test drive all the patterns. for HotDraw use examples heavily, but HotDraw comes with several applications that show concrete examples of applying the framework to a particular problem. Studying working examples is a timehonored way of learning a framework, and patterns are a way of reinforcing, encouraging, and system-atizing this method, not a replacement for it. It is interesting to note that examples also play a key role in design (c. f use cases [Jacobson] or walk-throughs [Wirfs-Brock et. al.]). This is just another example of the general rule that concrete examples are easier to understand than abstractions. Most of this paper is an appendix that contains an example of patterns for a framework. The framework is HotDraw, which is a framework for semantic graphic editors that was originally developed at Tektronix by Kent Beck and Ward Cunningham. It has been reimplemented several times. The latest version, and the one that the patterns describe, was written by Patrick McClaughry for ParcPlace ObjectWorks for Smalltalkrelease 4.0. This implementation was simpler than previous ones because the design of the user interface framework for Smalltalkrelease 4.0 was influenced by HotDraw. HotDraw is not unique as a graphics editor framework. Unidraw is a similar framework for the C++/X windows environment that is built upon the Interviews user interface framework [Vlissides]. DRAW-Master is a graphics editor framework for the C++/OS 2 and Windows environment that is built upon the GUI Master application framework [Veltman and Riksen]. HotDraw is simpler and less powerful than the others, but this simplicity makes it a better example for a paper like this. The first pattern describes the purpose of HotDraw. The patterns form a directed graph, with the first pattern as the entry point. Other patterns are arranged so that those closest to the first pattern are the ones that are most often used. For example, the second pattern describes how to make subclasses of Figure, which is something 66 that almost every user of HotDraw will need to know. The third pattern describes (among other things) how to install a handle on a figure, but the sixth pattern describes how to make new kinds of handles, which is usually unnecessary. The patterns assume that the reader knows Smalltalk. Some of the patterns contain fragments of Smalltalk code. They also assume that the reader is using Smalltalk, so they often refer to examples in HotDraw and imply that the reader can quickly look them up using the browser. This suggests that patterns would work well with an on-line documentation system, perhaps one that is based on hypertext. The set of patterns got its start at the workshop on "Towards an Architecture Handbook" organized by Bruce Anderson at OOPSLA'91. Kent Beck and I shared an interest in both HotDraw and Alexander's pattern language, so we took the opportunity to write some patterns for HotDraw. Later that fall I gave the patterns to some graduate students learning HotDraw, but the patterns were not helpful. At the time each pattern was only a paragraph, and both the examples and the theory of design of HotDraw were separated from the patterns. I studied Alexander's pattern language again, and realized that each pattern relied on examples and that he provided explanations for his patterns in terms of underlying theories of the properties of building materials or social interaction. When I integrated the examples with the patterns I found that the examples did not illustrate all the patterns, so I created another one or two examples. I put enough of the theory of design in the first pattern to define the main vocabulary and put the rest as far down in the patterns as possible, but far enough forward to both avoid duplication and to make sure the information was present before it was needed. The next group of people who read the patterns knew Smalltalk well, but most did not know HotDraw. Their feedback provided a few changes, but after a few iterations they were satisfied. The patterns are the only documentation for a version of HotDraw that has been distributed since early 1992, and users say they are satisfied with it. Since there are no complaints, it is hard to improve the patterns, which shows the weakness of this kind of informal testing. It would probably be worthwhile to try out the patterns in a controlled setting where it would be possible to watch how people use the patterns and what aspects of HotDraw are hard to learn. Writing the patterns was not hard once I figured out the format. Picking good examples is never easy, but the patterns showed the features that they needed to demonstrate. Probably the hardest part of writing a set of patterns for a framework is knowing the framework well enough to know how likely a feature is to be customized. The structure of the patterns seemed to help design them. Thinking about patterns as a directed graph made it easier to decide where to place examples and design information, and made it easier to analyze the patterns for completeness. Designing patterns for HotDraw took a lot of work, but it also helped clarify the design of the framework, so it was a useful exercise in itself. Designing patterns requires analyzing how people are expected to use the framework, and this points out ways that using it is awkward. Although the HotDraw patterns are easy to follow on paper, patterns might be even more effective as hypertext. A hypertext system could make it easier to follow links to patterns, to show more examples, to hide technical design explanations from casual readers, and to separate the various parts of a pattern. Several people who read earlier versions of this paper commented that patterns are similar to hypertext documentation systems that they have seen, though I have little experience with hypertext systems. The HotDraw patterns were an imitation of Alexander's pattern language, not hypertext or the MacApp cookbook. It is interesting that the final result is so similar to them. Patterns are a good way to describe frameworks because first-time users of a framework will usually not want to know exactly how it works, but will only be interested in solving a particular problem. As long as the patterns are powerful enough to describe most initial uses of the framework, it will meet the needs of the users. A set of patterns for a framework will be sufficient documentation for many of the framework's users. Only those who want to go outside the usual bounds of the framework or those with an emotional need to know how the framework works in detail will need to read traditional design documentation. The internal structure of a set of patterns minimizes the amount that has to be read to solve a problem, and also provides places to put design information. This paper is just a first step in creating a method for documenting frameworks. In the future, patterns should be tested against other ways of documenting a framework to see which best helps users build applications. Patterns should be used for larger frameworks to see whether they scale well, though Alexander's work suggests that they will. Although just a first step, the patterns for HotDraw in the appendix show that patterns are an attractive possibility for solving the problems of documenting frameworks. Kent Beck and Ward Cunningham not only invented HotDraw, they also introduced me to Alexander's pattern languages. This paper also owes a great deal to those who read it and provided it with muchneeded criticism, including Bruce Anderson, Kent Beck, Bob Hinkle, Brian Foote, Pat McClaughry, Carl McConnell, Bill Opdyke, Don Roberts, Michael Seif, Dan Walkowski, and the reviewers.
Some of the original work in frameworks REF discussed using design patterns as a way of describing frameworks.