I believe that a limited use of UML for both upfront design and for project documentation helps to improve the quality and reduce the expense of developing systems. However, there is a ”middle path” here: I have seen projects where too many resources were expended on creating UML design artifacts. If you start implementing a system and find that team members do not understand the architecture then your team is probably not spending enough time on preliminary design. On the other hand, if you find that the preliminary design is too detailed or needs to be frequently changed once the team starts implementation, then probably too much effort was spent designing the system before learning from early stage implementation code. If you use UML lightly, as I advocate, I believe that you will find the time well spent. Design, implementation, and testing are best done iteratively, with all three processes contributing to better understanding of the system that you are creating.

6.1 Developing an Automated Help Desk System

For the first example design, we will look at a project that I designed and implemented several years ago: an automated help desk system. This is a good example both because it is realistic (it is a real product that my company sells and uses at www.markwatson.com) and because it is a good example of a web based application. This system is implemented as a Java servlet.

Regardless of whether you are designing and implementing a commercial product or an Open Source project, or an in house project, or a project for a customer I recommend starting with this process:

• Describe briefly how people will use the new system (one or two paragraphs)
• Create one or more UML use case diagrams showing how the end user interacts with the system (note: if the new system is, for example, a back end server application, then the use case diagram could show how other system components interact with the new system)
• Talk with users of the new system, customers, etc. to make sure that they agree with the preliminary use description and use case diagram(s).

Here is a two-paragraph concept summary for the new product:

Figure 6.1 shows three end-user use cases for the help desk system.

Figure 6.1: UML Use Case Diagram for the Automated Help Desk System

Whenever I design and implement any system that contains a user interface, the first thing that I like to do is to cut the system in two: an engine and a presentation manager. Here, I will start by designing, then implementing, an engine that has a public interface for:

• Initialization from the XML product configuration file
• Generate an ”HTML menu” element with links for each product
• Generate an ”HTML data table” for any specified product including links for each FAQ for the product
• Generate an ”HTML data table” for any specified FAQ for a specific product
• For a sequence of key words, return a list (in decreasing order of relevance) of FAQs for a specified product
• For a natural language query, return a list (in decreasing order of relevance) of FAQs for a specified product

The public API for this interface is a ”contract” with the presentation manager. We will be free to change the internal implementation of the ”engine” class at will without breaking the system.

Figure 6.2 shows a detailed UML class diagram for the ”engine” part of the help desk system. We show classes as a box with three vertical panes: name of class, listing of class attributes, and listing of class methods. For high-level class diagrams, I often only specify the class name and leave the attributes list and methods list blank. It is often useful to list just the attributes (for data oriented classes like Faq and Product). A negative sign preceding an attribute or method implies that it is private while a plus sign indicates that it is public. Since the Help Desk product was a small effort, my design efforts were hand written on a few sheets of paper. Figure 6.2 was generated ”after the fact” by importing the existing Java source files into the Poseidon UML tool.

Figure 6.2: UML Class Diagram for the Help Desk ”Engine”

There is an important point here: developing software is a complex task; here, we have effectively partitioned the job into two loosely connected tasks (i.e., developing the an engine and a presentation manager) that can be written and debugged separately. With the public interface defined between these two parts of the system, we can proceed with the design, implementation, and unit testing of the engine without too much concern for the future task of designing, implementing, and testing the presentation manager.

There is another fairly obvious advantage to splitting the problem into two pieces: we might in the future want to create a standalone application for the automated help desk. In this case, we could set aside the presentation manager that is implemented as a Java servlet and write a new presentation manager with, for example, the Java Swing library.

Figure 6.3 shows a UML Sequence Diagram showing the interactions between a user (using a web browser), the HelpDesk servlet, and the HelpDesk Engine. Arrows represent requests or returned values from objects. This is general purpose: an arrow can be a method call between objects in the same Java Virtual Machine (JVM), a remote procedure call, etc. Time increases going down the page when looking at a sequence diagram.

Figure 6.3: UML Sequence Diagram for Help Desk System

6.2 Iterative Design and Development

It is difficult to know in advance all the features that a software system needs in order to be most convenient for users. As an example, after I did the preliminary requirements analysis in the last section for the help desk system, I started designing and coding the ”engine” module. As part of this effort, I set my emacs editor in XML mode and started to create an XML initialization file for the products on my www.markwatson.com web page. I quickly realized that there would be many common FAQs for several of my natural language processing products.

My first thought was to implement an inheritance scheme for products. However, this seemed to violate a basic object oriented concept: subclasses should obey an ”is a” type relationship with a super class. For example, a car ”is a” type of vehicle. However, it did not seem right to create dummy products that would be super classes of real products.

I decided that a simpler approach was better: independent of product definitions in a help desk XML initialization file, use a separate tag type, a ”FAQ set”. Common FAQs can be defined in a ”FAQ set” and any given product can simple list the FAQ sets that it uses.