Astute readers will notice that I took a detour in my last column from the logical progression of topics being presented. First we talked about CRC cards,1 then the CRC card session, then the outputs of a CRC card session. Next we discussed, in two parts, the use of the information gathered in CRC card sessions as input to two types of object-oriented analysis and design (OOA/D) methods. The next promised topic was the documentation of CRC card output for groups not using a formal method. My detour to talk about CRC card session facilitation was prompted by my experiences at Object Expo this summer. But this month we are back on track and ready to discuss the documentation of a CRC card design.
I have taken great pains in this column to emphasize the synergy of CRC cards with more formal OOA/D techniques. I believe, and my experience has supported, that use of an informal technique before choosing or before using a formal notation increases the quality of the design. Most importantly, using an informal technique to really understand the new paradigm can help newcomers avoid a major pitfall: the expectation that an OOA/D method will somehow do the job for them. Therefore, I like to emphasize whenever possible that the uses of CRC cards and of formal methods are not mutually exclusive.
But in actuality, most people who use CRC cards use just CRC cards and are not interested in or perhaps even familiar with the available methodologies. They use the cards to provide a process for learning the new paradigm and later for producing the object-oriented design (OOD). Generally, they are small teams of analysts, designers, and developers who have a history of doing ad hoc design individually as they develop but who fear that this approach will be less successful with an object-oriented model. CRC cards provide a good medium for project teams who have not done much design in the past to build a framework for an object-oriented implementation. They find that using CRC cards forces decisions to be made up front in a nonrestrictive and informal group setting where interactions and impacts of decisions are clear.
But a common question from these groups is "What do I need to write down about my design and what can I record to fully describe my design to someone else?" Even for projects that do not use formal methods and notations, it is often necessary to convey the essence of a CRC card design in a written form. There is no prescribed notation for this documentation, but there are three types of information that together describe a CRC card design fairly completely. We refer to these three types of information as (1) a class model, (2) class descriptions, and (3) scenario descriptions. Depending on a project's needs, different combinations of these may be generated. Exactly what written form this information takes is up to the project team. In this column, I will describe the types of information and give examples of realizations of these types for the electronic Checkbook application.
THE CLASS MODEL
The class model, the first component of the description of an OOD, consists of one or more pictures showing classes and their collaborations and inheritance relationships. The view provided is a static one between classes, similar to the view of the CRC cards when they are sitting on the table. This can be produced manually, as we have done in these columns, or the graph may be produced by an automated tool. Several CRC card tools now exist to capture these relationships (the subject of a future column). Other tools are also available to produce this picture, since many methodologists include such a graph as a part of their methods, e.g., the Wirfs-Brock2 collaboration graph or Booch3 class diagram. Superclass/subclass relationships can be shown on the same picture as collaborations or separately.
As an example, let us look at the class model for the Checkbook application. The Checkbook application team has separated the hierarchies from the collaborations. Figure 1 contains the Entry class hierarchy for the application. Subclasses in this picture point to their superclass.
The collaboration model for the main classes of the Checkbook application is presented in Figure 2. Classes are in ovals and lines are labeled with the responsibilities of the pointed-to classes. Separate collaboration models are often drawn for different subsystems of the application. For example, collaborations with the user interface classes and database classes for the electronic checkbook will appear in other pictures. These static collaboration models will "come alive" with actual objects when used with scenario descriptions, just as CRC cards "come alive" as objects when participants raise them during the execution of scenarios.
CLASS DESCRIPTIONS
The second component of the documentation of a design is the class descriptions. If more detail about each class at a design level is desired, some sort of class description should be added. This may be as simple as a copy of the cards themselves. Some projects like to use a more comprehensive form of documentation, where they can capture additional detail and more generous commenting. Use of a medium such as a UNIX manual page allows a project to specify types of data passed and returned from responsibilities. Other projects use the header files, created manually or tool generated. Man pages and header files are more appropriate after some prototyping has taken place. The class description should at the least contain high-level responsibilities for each class. As with the class model, card documentation is a natural output of many CRC card tools.
Table 1 is a sample set of class descriptions for the Checkbook application design. This information is transferred from the cards themselves, including the description and attributes from the back of the card.
SCENARIO DESCRIPTIONS
Since class models and class descriptions provide only static views of the application, they do not convey any sense of the flow of control of the system. The third type of information, scenario descriptions, describes how each scenario is fulfilled by the model. The addition of these to the set of documentation provides the necessary dynamic aspect.
We briefly discussed relationships among scenarios in a past column. There may be much repetition in "end-to-end" scenarios that the team executes, and a group may not always feel the need to repeat portions that they have executed before in detail. We can view these repeated sections as small scenarios, since we consider a scenario to be any activity of the application that requires a collaboration. Therefore, most scenarios will actually be made up of many smaller scenarios.
For example, multiple Checkbook scenarios will involve a sequence of interactions to search the Checkbook for a particular entry. Certainly the scenario to balance a Checkbook involves this subscenario, as do various report scenarios, e.g., "find all tax-deductible entries for the year." Table 2 describes this miniscenario. The Jacobson object interaction diagram4 for documenting use cases is an excellent way to describe scenarios (as we saw in a past column). A textual scenario table, such as Table 2, is not quite as effective, but is easier to draw. Such a table should be used in conjunction with the collaboration models, to display the fulfillment of each scenario.
Note that in this scenario table the initial client is referred to as someone because different types of objects will initiate this scenario at different times. By not specifying a particular initial client, the scenarios are more reusable.
The nesting relationships among scenarios can be utilized for a more efficient documentation. An example of this appears in Table 3 where uses SCENARIO 1 as a subset. The goal is to document scenarios in a modular manner, describing them in chunks that are large enough to be reused as a whole but small enough that pieces of them do not need to be repeated.
CONCLUSION
The appropriate design documentation will vary for, and thus must be determined by, each individual product team. I have seen small groups with no real need for detailed documentation at all. These groups found the creation and constant updating of documentation to be a complete waste of time. But many teams need to convey the essence of their OOD to management, new team members, maintainers, customers, or the outside world. These groups may change or supplement the documentation presented here to customize the design to their environment. But the class model, class descriptions, and the scenario descriptions should form a reasonable foundation for their efforts.
References
[1]Wilkinson, Nancy M. Using CRC Cards: An Informal Approach to Object-Oriented Development, SIGS Books, New York, 1995.
[2]Wirfs-Brock, Rebecca, B. Wilkerson, and L. Wiener. Designing Object-Oriented Software, Prentice Hall, Englewood Cliffs, NJ, 1990.
[3]Booch, G. Object-Oriented Analysis and Design with Applications, 2nd ed., Benjamin-Cummings, Redwood City, CA, 1993.
[4]Jacobson, I., M. Christerson, P. Jonsson, and G. Overgaard. Object-Oriented Software Engineering, Addison-Wesley, Reading, MA, 1992.