----------------------------------------------------------------- Name: Greg Butler Affiliation: Department of Computer Science Concordia University 1455 de Maisonneuve Blvd West Montreal Quebec Canada H3G 1M8 gregb@cs.concordia.ca http://www.cs.concordia.ca/~faculty/gregb/home.html ----------------------------------------------------------------- Position paper for OOPSLA97 workshop on Object-Oriented Design Quality Documenting In Good Design by Greg Butler Viability of an architecture, and keeping true to the architectural vision are key points in a successful OO project, according to Booch. This suggests two key qualities: fitness for purpose, and transparency of rationale or vision for a "good" OO design. How do you achieve these qualities, and how do you review for them? One suggestion is to look more closely at documentation than models. The hypothesis is that simplicity and clarity of documentation is a compelling argument that the underlying architecture and design must also be simple and clear. This may not be the endpoint of the review, but it does mean that the design is transparent enough to be able to concentrate on other issues. Documenting for Reuse of Frameworks The above point of view arose while considering the reuse of application frameworks. Novice application developers face a steep learning curve when they first meet a framework, and various suggestions have been made about how to document a framework to best address the issue. Their effectiveness is rarely supported by experimental data. We distilled a set of guidelines for documenting a framework, and then a student, Pierre Denommee, did a case study. He developed a simple game framework, and documented it according to the guidelines. The feedback from the documentation effort to the design, and its consequent improvement in viability, simplicity, and clarity were evident even at an anecdotal level. So just creating end-user documentation had a positive effect on design quality. The next step is to look at the simplicity and clarity of that documentation. This is happening in the course of writing his thesis, and my review of his writing. Again, it is evident that convoluted documentation often means a convoluted design (and not just a confused writer) where concepts and responsibilities are not clearly delineated. Styles of Documentation The source code of example applications 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. A recipe describes how to perform a typical example of reuse during application development. The information is presented in informal natural language, perhaps with some pictures, and usually with sample source code. A cookbook is a collection of recipes. 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. A pattern language provides 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 interface contract of a class provides a specification of the class interface and class invariants in isolation. A contract specifies the type constraints given by the signature of a method, and the interface semantics of the method. An interaction contract deals with the co-operative behavior of several participants that interact to achieve a joint goal. It specifies preconditions on participants required to establish the contract, and the invariant to be maintained by these participants. A design pattern provides an abstraction above the level of classes and objects. Design patterns capture design experience at the micro-architecture level, by specifying the relationship between classes and objects involved in a particular design problem. 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 reference manual for an object-oriented system consists of a description of each class, together with global variables, constants, and types. Typically, a class description presents the purpose or responsibility of the class, the role of each data member, and some information about each method. Guidelines for Framework Documentation to Assist Application Developers All that is necessary for an application developer is overview, examples, and recipes. 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. A hotspot that is very flexible may need several examples to illustrate its range of variability, from straightforward customization through to elaborate customization with all the bells and whistles. One of the simpler example applications should be used in the overview presentation. The cookbook recipes will use sample source code from the example applications. 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. There may also be cross-references to any other available documentation (such as a reference manual, contracts, or design patterns). Biography Gregory Butler is Associate Professor in Computer Science 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, Zuerich 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 Universitaet Bayreuth. -----------------------------------------------------------------