Framework Design and Documentation

FWF Project P11350-TEC
September 1996 - August 1998

This project aims at the development of techniques and tools for designing and documenting frameworks. The planned work continues the fruitful co-operation of Prof. Mössenböck and Prof. Koskimies in the context of the project "Class Management Techniques in the Oberon-2 Environment" supported by the "Fonds zur Förderung der wissenschaftlichen Forschung" and the Academy of Finland ([KM95a], [KM95b], [MK95], [KM95c], [KM95d]). A central paradigm in the research will be the active document. This concept is supported in a simple and elegant form by the Oberon environment which will be used as an implementation platform, but the essential results will be independent of the language and of the environment.

The research consists of several subgoals which are elaborated partly in parallel:

Active Pictures in Framework Documentation

Technical artifacts are often described by graphical plans (e.g., circuit diagrams, architecture plans, etc.). This is also the case in software development (SADT diagrams, OMT diagrams, snapshots of data structures, etc.). The problem with such diagrams is that they tend to become quite complex and difficult to read. When presented the full picture, it is often difficult to find out in which order to read it. Often the picture shows information that is not relevant at the same time (e.g., different layers, different subsystems). When a person draws such a picture on paper, one can see how the drawing evolves, but these steps are not visible any more in the final picture.
Therefore, our idea is to store a picture not as a whole but as a sequence of drawing steps that can be played forwards and backwards like a film. The user can then see how the drawing evolves. At every step, he can get explanatory comments so that he can understand what goes on. He can even explore different alternatives which lead to different pictures. We would also like to include animation so that it should be possible, say, to show how a data structure smoothly changes as a result of some algorithm.
It should be possible to include active pictures in texts and even in the source code of programs so that they can be combined with code and documentation. The reader of a program text would then be able to get graphic comments and even to look at a film that shows dynamic aspects of the code.
The drawing facilities should not be restricted to a certain kind of diagrams but should be general enough so that in principle any picture can be created. We plan to implement the drawing facilities as an extension of an existing graphics editor so that the implementation effort should be relatively low and the user does not have to learn a completely new tool.
In the context of the proposed project we would like to find out how well active pictures are suited to draw and read object-oriented design diagrams (e.g., OMT [Rum91], RDD [WWW90], Booch [Boo91]). In particular we want to apply them to frameworks and design patterns [GHJV95]. For this purpose we plan to make the pictures reactive and explore different kinds of reaction (e.g., hypermedia links, on demand information, automatic generation of code skelettons, etc.). Another interesting aspect is to integrate active pictures with the active texts that we already developed thus leading to general active documents.
Expected result: A tool for producing active pictures, and techniques to use active pictures for documenting frameworks.

Extensions of the OMT Notation for Specifying the Hot Spots of Frameworks

The OMT Notation [Rum91] has become a de facto standard for the graphical documentation of object-oriented programs. This notation provides various kinds of diagrams that show the static and dynamic behaviour of programs so that one can express the components of a system and their interaction.
Object-oriented software, however, is usually not designed from scratch but derived from some existing framework. The designer of such software must understand the framework and clearly see where it is possible to hook in application-specific code. These hook points are often called the hot spots of the framework since they are the places where new functionality can be brought in. The OMT notation (or any other notation) does not convey this information sufficiently well. We would therefore like to explore new ways to make the hot spots explicit. This could be done by an extension of the notation or by making use of active pictures so that the relevant hot spots are shown and explained on demand.
Information that could be provided is among others: What classes have to be extended in order to get some desired effect? What methods have to be redefined for that? What are the pre and post conditions of these methods? Using active pictures it is also possible to show how a framework works. Several scenarios can be displayed as a set of films that can be inspected to see in which context the redefined methods are invoked.
It is also interesting to develop tools that support the drawing of a specific kind of diagrams, for example commands that help to draw diagram components and to keep them consistent. These tools are of course notation-specific (e.g. OMT tools, RDD tools) and could be seen as a layer above the general active pictures facilities.
Expected result: A tool-supported notation for specifying and browsing the hot spots of a framework.

Active Cookbooks for Extending Frameworks

The idea of active cookbooks has been put forward in [PPS95]. A cookbook is a recipe that explains how to perform a certain task (e.g., how to extend a framework). An active cookbook is not just a textual recipe but also contains interactive elements that can provide information on demand or help to perform certain subtasks in a (semi-) automatical way.
A cookbook for frameworks often has to reference pieces of code that should be read or modified as a certain step of the recipe. These references should not be copies of the code (which would soon become inconsistent) but should refer to the actual code itself. This helps to keep the cookbook up to date even if the framework is modified. We plan to develop new kinds of text elements that are hypertext links which do not lead to a specific target point but rather reference a target stretch of text, i.e., provide a window into the framework.
Expected result: Tools to develop active cookbooks; documentation of existing frameworks as case studies.

References

[Boo91] Booch G.: Object-Oriented Design with Applications. Benjamin Cummings, 1991.

[BJ94] Beck K., Johnson R.: Patterns Generate Architectures. In: ECOOP '94, LNCS 821, 139-149.

[GHJV95] Gamma E., Helm R., Johnson R., Vlissides J.: Design Patterns: Elements of Object-Oriented Software Architecture. Addison-Wesley 1995.

[JKN95] Järnvall E., Koskimies K., Niittymäki M.: Object-oriented language engineering with TaLE. To appear in Object-Oriented Systems, 1995.

[Joh92] Johnson R.E.: Documenting Frameworks with Patterns. In: OOPSLA '92, Sigplan Notices 27(10), October 1992, 63-76.

[KM95a] Koskimies K., Mössenböck H.: Designing an Object-Oriented Framework for Language Implementation. Report 2, Department of Systems Software, University of Linz, 1995.

[KM95b] Koskimies K., Mössenböck H.: Designing a framework by stepwise generalizaton. To appear in ESEC '95, Barcelona 1995.

[KM95c] Koskimies K., Mössenböck H.: Viewing object-oriented programs through scenario diagrams. In Proc. Fourth Workshop on Programming Languages and Software Tools, Visegrad, Hungary, June 1995, 1-8.

[KM95d] Koskimies K., Mössenböck H.: SCENE: Using active text and scenario diagrams for illustrating object-oriented programs. Manuscript, 1995.

[Knu84] Knuth D.E.: Literate Programming. The Computer Journal, vol. 27, no.2, 1984, 97-111.

[MK95] Mössenböck H., Koskimies K.: Using active text for structuring and understanding source code. Submitted for publication, 1995.

[Pre95] Pree W.: Design Patterns for Object-Oriented Software Development. Addison-Wesley 1995.

[PPS95] Pree W., Pomberger G., Schappert A., Sommerlad P.: Active Guidance of Framework development. In Software - Concepts and Tools, Springer-Verlag 1995, 1-10.

[Rum91] Rumbaugh J., Blaha M., Premerlani W., Eddy F., Lorensen W.: Object-Oriented Modelling and Design. Prentice-Hall, 1991.

[WGM88] Weinand A., Gamma E., Marty R.: ET++ - An Object-Oriented Application Framework in C++. In: OOPSLA '88, Sigplan Notices 23(11), October 1988, 46-57.

[WWW90] Wirfs-Brock R., Wilkerson B., Wiener L.: Designing Object-Oriented Software. Prentice Hall, 1990.