Greg Butler, Pierre Denommée
Department of Computer Science
Concordia University
Montreal, Quebec, H3G 1M8 Canada
Tel: (514) 848-3031
Tel: (514) 848-3000
Fax: (514) 848-2830
Email:
gregb@cs.concordia.ca
URL:
http://www.cs.concordia.ca/~faculty/gregb/home.html
Object-oriented frameworks offer a concrete reusable architecture for a family of applications. An expert can very rapidly develop applications using the framework, however, for the novice there is a steep learning curve. This is an obstacle to reuse.
How to develop a framework is another issue in this area. Identifying the required flexibility for the family of applications and designing mechanisms that provide this flexibility is the problem. The solution combines domain analysis, software evolution, and design patterns.
This position paper looks at application frameworks and how they should be documented in order to facilitate reuse and development.
Keywords: Reuse, design, framework, design pattern, architecture, formal m ethods
Workshop Goals: Learning; networking; understanding
Working Groups: reuse and product lines; object technology, architectures and domain analysis; domain engineering tools
Butler is interested in constructing frameworks for scientific knowledge-based systems, and the software aspects of developing, documenting, and reusing them. His background in computer algebra systems [B89-92] convinced him that a more flexible environment, using a single language, C++, is needed to research the issues of software architectures and their integration for computer algebra systems. Also, there is a great need from researchers in algebraic algorithms for a software library. Since moving to Concordia University at the end of 1991, Butler's research has focussed on C++ libraries and frameworks, issues of reuse, and issues of reliability (which includes correctness).
In the past four years Butler has been actively leading a discussion group at Concordia on object-oriented design, lately concentrating on design patterns. He also teaches a course on object-oriented design based on OMT [RBPEL91] that also includes material on reuse. In Winter 1996 the course used the ET++ framework [Lew+95, Ch. 7,] as a source of design examples. Furthermore, the ET++ framework is the basis of several student projects, so we have first-hand knowledge of the steep learning curve for frameworks.
On the research side there is ongoing work on
The steep learning curve of application frameworks hampers their reuse, or efficiency of reuse. This is an instance of the understandability problem in reuse. Documentation of a framework must address this obstacle to the effective reuse of frameworks. It is complicated by the fact that different audiences require different information: a regular re-user customizes (or instantiates) a framework in an expected way, and the documentation can address each expected customization an advanced re-user instantiates the framework in an unexpected way by combining the different degrees of freedom (so called ``hot spots'') in a novel way: this re-user must understand the principles and constraints of the hot spots, and their collaboration; a framework developer will evolve or generalize the range of applicability or flexibility of a framework: this is similar to general software evolution combined with issues of framework development; and a developer of another framework wants to learn the principles behind the flexibility of the example framework,the so-called design patterns. Documenting the evolution of a framework is a particularly challenging problem.
In our position we address the largest class of reusers: the application developers who reuse the framework as it was intended to be reused. We summarize guidelines on how to document a framework to assist application developers. The guidelines emphasize (1) prescriptive (``how-to'') information -- since this is what application developers need; (2) concrete examples -- to counter the abstractness of a framework design; and (3) a graded, or spiral, organization of information -- to minimize the amount of information needed, and to focus on the task at hand.
First, the application developers will need a context for the framework, so an overview of the framework should be prepared, both as a live presentation and as the first recipe in the cookbook.
Second, a set of example applications that have been specifically designed as documentation tools is required. The examples should be graded from simple through to advanced, and should incrementally introduce one hotspot at a time.
Third, a cookbook of recipes should be written, and organized along the lines of Johnson's pattern language. The recipes should use the example applications to make their discussion concrete. There will be cross-references between recipes, and between recipes and source code. A good cookbook can use just pen and paper, however, a hypertext browser will help navigate cross-references.
Unfortunately, there is often little, or only anecdotal evidence of the impact of the style of documentation on actual reuse of the framework.
We discuss the various styles of documentation that have been used to describe frameworks. The ET++ framework comes with example applications, a cookbook, and a reference manual, and the PhD theses of Gamma and Weinand discuss the architectural rationale using design patterns. Lajoie and Keller [LK95] adopt an approach that combines recipes, design patterns, and contracts, all cross-referenced to document the ET++ framework.
Example Application The source code of example applications that have been constructed using the framework is often the first and only documentation provided to application developers. Documentation requires a graded set of training examples. Each should illustrate a single new hotspot, starting with the simplest and most common form of reuse for that hotspot, and eventually providing a complete coverage. Most cookbooks revolve around a small number of simple example applications.
Recipe A recipe describes how to perform a typical example of reuse during application development [Pree95, Ch. 3,]. The information is presented in informal natural language, perhaps with some pictures, and usually with sample source code. Although informal, a recipe often follows a structure, such as sections on purpose, steps of the recipe, cross references to other recipes, and source code examples.
Cookbook A cookbook is a collection of recipes [Pree95, Ch. 3,]. A guide to the contents of the recipes is generally provided, either as a table of contents, or by the first recipe acting as an overview for the cookbook. Many systems use cookbooks for documentation.
Pattern Language Johnson [John92] introduced an informal pattern language that can be used for documenting a framework in a natural language. He applied his approach to HOTDRAW, a framework for drawing editors. Patterns provide a format for each recipe, and an organization for the cookbook. The organization follows a spiral approach where recipes for the most frequent forms of reuse are presented early, and where concepts and details are delayed as long as possible. The first recipe is an overview of the framework concepts and the other recipes.
Motif Lajoie and Keller [LK95] introduce the term motif for Johnson's patterns in order to avoid confusion with design patterns. They use a template for a motif description that has a name and intent, a description of the reuse situation, the steps involved in customization, and cross references to motifs, design patterns, and contracts. The design patterns provide information about the internal architecture, and the contracts provide more rigorous description of the collaborations relevant to the motif. They applied their approach to ET++ [Lew+95, Ch. 7,].
Interface Contract A contract is a specification of obligations. The interface contract of a class [Meye92] provides a specification of the class interface and class invariants in isolation.
Interaction Contract A contract is a specification of obligations. An interaction contract [HHG90, Holl92] deals with the co-operative behavior of several participants that interact to achieve a joint goal. The contract specifies a set of communicating participants and their contractual obligations: the type constraints given by the signature of a method, the interface semantics of the method, and constraints on behavior that capture the behavioral dependencies between objects. Helm et al wrote a few interaction contracts for the model-view-controller paradigm.
Design Pattern A design pattern presents a solution to a design problem that might arise in a given context [GHJV94]. The description of a design pattern explains the problem and its context, the solution, and a discussion of the consequences of adopting the solution. The problem might be illustrated by a concrete example. The solution describes the objects and classes that participate in the design, and their responsibilities and collaborations. A collaboration diagram may be used to represent the same information. Examples of the solution being applied in concrete situations may be provided. The analysis of benefits and trade-offs of applying the pattern is an important part of the design pattern description.
Beck and Johnson [BJ94] illustrate the use of design patterns in developing the architecture for HOTDRAW, a framework for drawing editors. Design patterns are good at describing architectures.
Framework Overview Setting the context of a framework is a first step in helping an application developer reuse a framework. A framework overview defines the jargon of the domain and delineates the scope of the framework: just what is covered by the framework and what is not, as well as what is fixed and what is flexible in the framework. A simple application can be reviewed, and an overview of the documentation can be presented. A framework overview is often the first recipe in a cookbook.
Reference Manual A reference manual for an object-oriented system consists of a description of each class. Typically, a class description presents the purpose or responsibility of the class, the role of each data member, and some information about each method. A method description presents the functionality of the method, its pre- and post-condition, and an indication of which data members it affects or uses. For framework documentation, the descriptions can include additional material concerning the role of a class or method in providing flexibility for a hotspot, particularly whether a class is intended to be subclassed or a method to be overridden.
Gregory Butler is Associate Professor in Computer Science and a member of Centre Interuniversitaire en Calcul Mathématique Algébrique (CICMA) at Concordia University, Montreal, Canada. His research interests are reusable object-oriented design, software architectures, C++ libraries and frameworks for computer algebra systems which integrate knowledge-based facilities. He obtained his PhD from the University of Sydney in 1980 for work on computational group theory. He spent 1976/77 at ETH, Zürich as part of his doctoral studies, and for two years, 1979-1981, was a postdoctoral fellow at McGill and Concordia Universities in Montreal. He was on the faculty of the Department of Computer Science at the University of Sydney from 1981 to 1990. He has held visiting positions at the University of Delaware and Universität Bayreuth.
Pierre Denommée is a Masters candidate at Concordia University, Montreal, Canada. His research topic is on documenting and understanding application frameworks.