Pattern: Customization Points

You are documenting a framework to provide application developers with prescriptive and descriptive information capable of helping them customize the framework.

To help application developers customize a framework effectively, the documentation should be organized in a way that can help readers obtain detailed information quickly, both prescriptive and descriptive, about the framework parts strictly required to customize, and how to customize them, in order to implement the specific features of the application at hands.

Although examples, cookbooks and recipes are good at providing prescriptive information, they might not be sufficient to allow customization of specific parts or in specific situations not predicted in other forms of documentation.

How to help readers know which framework parts are customizable?

How to help readers learn in detail how to customize a specific part of a framework?

Task-orientation. Readers want to learn in detail how to use a certain customizable part of the framework, so the documentation must focus on customization tasks imposed by the framework, which users really need to perform, as perceived in the recipes of the framework’s cookbook.

Balancing Prescriptive and Descriptive information. To be effective, the documentation about how to customize a specific part of a framework must achieve a good balance between the level of detail of the instructions provided to guide the usage of that framework’s part, and the level of detail and focus used to communicate how it works, i.e. its design internals.

Different Audiences. An application developer is a software engineer who is responsible for customizing a framework to produce the application at hands. Application developers want to identify which customizations are needed to produce the desired application, and to know how to implement them, instead of understanding why it must be done that way. The application developer thus needs prescriptive information capable of guiding her on finding out which hot spots must be used, which set of classes to subclass, which methods to override, and which objects to interconnect. It must be expected that the application developer possibly is not knowledgeable on the application domain and not an experienced software developer.

Completeness. Readers appreciate complete information, i.e. that all possible customizations are mentioned with all the possible detail, which is not always feasible as it largely depends on the reader’s point of view and the tasks to support.

Easy-to-use. Independently of the level of completeness and detail, the resulting documentation must be easy to use (clarity, easy-to understand and navigate).

Provide a list of the framework’s customization points, also known as hot-spots, i.e., the points of predefined refinement where framework customization is supported, and, for each one, describe in detail the hooks it provides and the hot-spot subsystem that implements its flexibility.

To allow easy retrieval, provide lists of customization points ideally organized by different criteria, being probably the following the most important ones:

• by kind of framework functionality, to provide a black-box reuse-oriented view; especially useful when looking for possibilities of customization related with a set of features in mind;
• by framework parts and modules, to provide a white-box reuse-oriented view; especially useful when looking for possibilities of customization related with a specific framework part or module.

Hot-spot. Customization is supported at points of predefined refinement, called hot- spots, using general techniques, such as, abstract classes, polymorphism and dynamic binding. A hot spot usually aggregates several hooks within it and is implemented by a hot-spot subsystem that contains base classes, concrete derived classes and possibly additional classes and relationships.

Hook. Hooks present knowledge about the usage of the framework and provide an alternative view to design documentation. Hooks provide solutions to very well- defined problems. They detail how and where a design can be changed: what is required, the constraints to follow, and effects that the hook will impose, such as configuration constraints.

A hook description usually consists of a name, the problem the hook is intended to solve, the type of adaptation used, the parts of the framework affected by the hook, other hooks required to use this hook, the participants in the hook, constraints, and comments. Hooks can be organized by hot spot; as said before, a hot spot tends to have several hooks within it. The usage of hooks can be semi-automated with the help of wizards, for example.

Hot-spot subsystem. The hot-spot subsystem supports variability either by inheritance or by composition. The variability is often achieved by the dynamic binding of a template method t(), an operation from a class T, that calls a hook method h(), an abstract operation from a base class, via a polymorphic reference typed with the class of the hook pointing to an operation h’(), from a subclass of H, that overrides h(). With inheritance, the polymorphic reference is attached to the hot-spot subsystem; with composition the reference is contained in it. The figure below shows an example of both kinds of hot-spot subsystems.

Despite providing an organized list of customization points being of great value in terms of documentation completeness, they are not so frequently used as examples, cookbooks and recipes in the documentation of the most popular frameworks, namely those we have been referring so far in these patterns. We discuss below how these customizations are documented in some well-known frameworks.

JUnit. The major kind of reuse that JUnit was designed for is very simple and consists only on writing and organizing tests, so its documentation is mostly targeted to explain how to do these tasks, which is simply and perfectly documented as cookbooks and recipes in the document “JUnit Cookbook” document.

However, some more customizations can be done with JUnit, such as test runners, and test decorators, but information about these and other less used customization points is only briefly mentioned in the “JUnit FAQ” document and in the low- level Javadoc documentation. The figure below shows an enumeration of other possible customizations of JUnit (version 3.8.2) described in its accompanying documentation. How such customizations are implemented, i.e. their hot-spot subsystems, are not documented and only identifiable by direct source code inspection.

Swing. When compared with JUnit, Swing is a very large framework providing a huge number of possible customization points, which are organized in its documentation in a simple and easy to browse manner that uses different levels of depth and detail. The most intuitive list is probably the one provided by the “Visual Index to the Swing Components” (see figure below).

A good and more complete alternative to the visual index to learn what can be customized in the Swing framework is the list that enumerates how-to use each of the key components (figure below left), which gives access to more detailed lists of possible customizations of each component (figure below right). Even more detailed information about how the flexibility is supported in each customization point although not explicit in the documentation, is left to the reader to explore by herself, probably using the Javadoc comments and source code inspection.

By providing framework users with an organized and exhaustive list of all the predefined customization points, or at least, the most important and frequently used, readers can evaluate if the framework is applicable to the problems at hands, and therefore to decide with more confidence whether or not to reuse it.

After knowing the points to customize, whether the knowledge was gathered from own experience, others’ knowledge, or documentation (e.g. CUSTOMIZATION POINTS, GRADED EXAMPLES, or COOKBOOK AND RECIPES), framework users can then start learning which tasks must be carried on to customize them properly, possibly supported by the prescriptive information provided by the COOKBOOK AND RECIPES related with those customization points. In addition, they can use the descriptive information provided for each CUSTOMIZATION POINT to learn more about how its flexibility is supported, and the information about its DESIGN INTERNALS to know in detail how the framework is designed.

Although adding some possible redundancy, lists of CUSTOMIZATION POINTS are easy to use and browse and provide a good balance between prescriptive and descriptive information thus being a good complement to the prescriptive information of COOKBOOKS AND RECIPES and the descriptive information of DESIGN INTERNALS.