Banaras Hindu University

A Course on Software Reuse by Design Patterns and Frameworks

by Dr. Manjari Gupta Department of Computer Science Banaras Hindu University

Lecture 10 Framework Documentation Using Pattern Language

 means of both building and describing frameworks.  many formats are to framework documentation  describe the common problems that occur within a domain  describe how the framework can be used to addresses these issues Pattern language

 Johnson was the first person to propose the use of a pattern language to document frameworks  describe solutions to the common problems that face developers trying to reuse a framework  presented in natural language  can include examples and illustrations to help communicate the problem being addressed Johnson’s Pattern Language

 is organised into a directed graph where  the nodes of the graph form the patterns and  the arcs represent references between patterns.  Common frequently required patterns are presented closer to the root of the graph  more obscure and technical patterns are pushed out toward the edges of the graph  root of the graph is a special overview pattern Johnson’s Pattern Language

 The format of each pattern  name to identify the pattern,  a description of the problem it solves,  a discussion on possible solutions and their merits, and  a summary of how to best solve the problem.  pattern format is textual in nature  are no formal guidelines provided to support neither the identification nor description of useful patterns Johnson’s Pattern Language

 three important areas for framework documentation to address  purpose, how to use and design  patterns can address all of these areas  Example programs are closely integrated. Johnson’s Pattern Language

 integrates design patterns and contracts together within a pattern language structure.  taxonomy of reuse levels  small, medium and large scale activities  Based on different types of knowledge that are required by developers during reuse Lajoie and Keller Pattern Language

 At the smallest scale  reuse is concerned with describing class and method level behaviours,  At the medium level  the emphasis changes to inter class communication  At the largest scale  developers are concerned with the gross behaviour displayed by entire applications. Lajoie and Keller Pattern Language

 The documentation technique focuses on the medium level of reuse  developers are challenged by their lack of course grained knowledge about a system.  micro-architecture  a collaboration of classes, which represent some important unit of behaviour, offered by the framework.  experienced framework developers use such a course-grained model of the system  they think of framework modification in terms of composing and altering these larger units of code rather than individual classes.  describes micro-architectures using a combination of design patterns and a specialised implementation of Helm's contracts Lajoie and Keller Pattern Language

 To tie the individual micro architecture descriptions together an implementation of Johnson's pattern language (renamed as motifs) where the descriptions have been altered to include references to design pattern and contract information.  a separation in the documentation used to describe the framework and example applications  recursive style of documentation Lajoie and Keller Pattern Language

 motifs describe the first two of these  the use of design patterns and contracts describes the design of the framework Lajoie and Keller Pattern Language

 incorporate many of the ideas expressed in patterns, motifs and hooks into one form of documentation.  derived from industrial experience  work is grounded in the psychology literature on how humans learn and construct mental models.  documentation is classified into a pyramid like structure  abstract ideas gradually give way to more concrete and detailed ideas as the developer works through the documentation. Meusel’s Pattern Language

 The pyramid is organised into three levels  framework selection,  standard use and  detailed design.  These levels are directly comparable to framework documentation in terms of purpose, how to use and design Meusel’s Pattern Language

 Framework selection is supported by the use of a catalogue pattern  describes an overview of the domain and capabilities offered by the framework.  application patterns  Describes the standard use of the framework  resemble Froelich hooks and Lajoie motifs in terms of their structure and references to other forms of documentation. Meusel’s Pattern Language

 Name: identifies the framework  Type: describes the construction of the framework, white box, black box etc,  Keywords: suggest the purpose of the framework  Problem description: a description of the domain that this framework addresses  Solution: Major capabilities and design concepts embodied by the framework  Examples: list of typical applications  Documentation: description of available documentation and suggested entry points  Other frameworks: names of similar frameworks to investigate Catalogue pattern format

 Name: identifies the purpose of the pattern  Context: describes the environment in which the problem occurs  Problem: identifies the problem addressed by this pattern  Solution flowchart: algorithm that addresses the problem  Explanations: further detail on important stages of the solution (including example code)  Examples: links to examples that illustrate this problem  Design information: Links to further more detailed documentation Application pattern format

 Meusel et al suggest  hotspots should be used as a mechanism to identify the appropriate areas to document using application patterns.  The detailed design of the framework is documented using a mixture of different pre-existing techniques including  design patterns, class references (like JavaDoc) and object model notations.  the use of tools to reverse engineer design information from the framework itself. Meusel’s Pattern Language

 Each level of documentation is linked to the level below via hypertext wherever appropriate.  emphasise the opportunistic use of documentation to support specific queries about a framework  encourage the developers to test their hypotheses against the framework documentation.  suggest that appropriate search engines should be provided to facilitate this usage of the documentation. Meusel’s Pattern Language

 comprises a set of interdependent patterns  the patterns are organized  According to the nature of the problems addressed  in process and artefact patterns Aguiar and David Pattern Language

 process patterns  address questions such as how to do it? Which activities, roles and tools are needed?  are strictly related with the process of cost effectively documenting frameworks.  Artifact patterns  address questions such as which kinds of documents to produce? what should they include? how to relate them? Aguiar and David Pattern Language

 are related with the process of documenting object- oriented frameworks  life cycle of framework documentation can be organized in five basic activities  configuration, production, organization, usage, and maintenance. Documentation process patterns

Documentation process patterns and their relationships

 address problems related with the documentation itself  seen as an autonomous and tangible product independent of the process used to create it.  provide guidance on choosing the kinds of documents to produce, how to relate them, and what to include there Artefact Patterns

 From the reader’s point of view,  on providing accurate task-oriented information,  well-organized,  understandable, and  easy to retrieve with search and query facilities.  From the writer’s point of view,  selecting the contents to include,  choosing the best representation for the contents, and  organizing the contents adequately Artefact Patterns

Documentation artifact patterns and their relationships