Introduction

Design must define enough of the system so that it can be implemented unambiguously. What constitutes enough varies from project to project and company to company.

In some cases the design resembles a sketch, elaborated only far enough to ensure that the implementer can proceed (a "sketch and code" approach). The degree of specification varies with the expertise of the implementer, the complexity of the design, and the risk that the design might be misconstrued.

In other cases, the design is elaborated to the point that the design can be transformed automatically into code. This typically involves extensions to standard UML to represent language and/or environment specific semantics.

The design may also be hierarchical, such as the following:

• a high level design model which sketches an overview of the overall system
• a subsystem specification model which precisely specifies the required interfaces and behavior of major subsystems within the system
• a detailed design model for the internals of subsystems

The  Development Case should define how the Design Model is realized in the project's specific process, and how/if the model relates to other models and to the implementation. Details should be captured in the  Project-Specific Guidelines.

The sections below describe some different options for relating a design and implementation, and discuss benefits and drawbacks of these approaches.

Sketch and Code

One common approach to design is to sketch out the design at a fairly abstract level, and then move directly to code. Maintenance of the design model is manual.

In this approach, we let a design class be an abstraction of several code-level classes. We recommend that you map each design class to one "head" class that, in turn, can use several "helper" classes to perform its behavior. You can use "helper" classes to implement a complex attribute or to build a data structure that you need for the implementation of an operation. In design, you don't model the "helper" classes and you only model the key attributes, relationships, and operations defined by the head class. The purpose of such a model is to abstract away details that can be completed by the implementer.

This approach is extended to apply to the other design model elements. You may have design interfaces which are more abstract than the code-level interfaces, and so on.

Round-Trip Engineering

In round-trip engineering environments, the design model evolves to a level of detail where it becomes a visual representation of the code. The code and its visual representation are synchronized (with tool support).

The following are some options for representing a Design Model in a round-trip engineering context.

High Level Design Model and Detailed Design Model

In this approach, there are two levels of design model maintained. Each high level design element is an abstraction of one or more detailed elements in the round-tripped model. For example, a design class may map to one "head" class and several "helper" classes, just as in the "sketch and code" approach described previously. Traceability from the high level design model elements to round-trip model elements can help maintain consistency between the two models.

Although this can help abstract away less important details, this benefit must be balanced against the effort required to maintain consistency between the models.

Single Evolving Design Model

In this approach, there is a single Design Model. Initial sketches of design elements evolve to the point where they can be synchronized with code. Diagrams, such as those used to describe design use-case realizations, initially reference sketched design classes, but eventually reference language-specific classes. High level descriptions of the design are maintained as needed, such as:

• diagrams of the logical structure of the system,
• subsystem/component specifications,
• design patterns / mechanisms.
  

Such a model is easier to maintain consistent with the implementation.

Specification and Realization Models

A related approach is to define the design in terms of specifications for major subsystems, detailed to the point where client implementations can compile against them.

The detailed design of the subsystem realization can be modeled and maintained separately from this specification model.

See Guideline: Design Subsystem for guidelines related to subsystem specifications and realizations, and when they should be used.