Documenting frameworks using patterns

TL;DR: This paper shows one way to document frameworks with patterns, and includes a set of patterns for HotDraw as an example to see how well patterns work to describe a framework.

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 framework without having to understand in detail how it works, and can teach many of the design details embodied in the framework. This paper shows how to use patterns to document a framework, and includes a set of patterns for HotDraw 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. To be presented at OOPSLA’92. 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 framework 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. 1. A Format for Patterns 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. 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 Pattern 4: Complex Figures Some figures have a visual presentation with internal structure. For example, they may have attributes that are displayed by other figures. It should be possible to compose them from simpler figures. Complicated figures like PERTEvent can be thought of as being composed of simpler figures. For example, a PERTEvent has a RectangleFigure and several TextFigures for the title, the duration, and the ending date. Complex figures like PERTEvent are subclasses of CompositeFigure. A CompositeFigure is a figure with other figures as components, and it displays itself by displaying its components. 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.