Design Guidelines		 Describes the design and implementation guidelines.
Worker: Architect
Template: Word template

Purpose To top of page

Design Guidelines is a product of architecture definition. Many people will need this document because it describes the guidelines to be followed during design, architectural design, and implementation.

  • It is an artifact created and maintained by the Architect, and serves as a communication medium between the Architect and other developers.
  • Designers will use it as a reference when defining operations on design classes, and when adjusting design classes to the implementation environment.
  • Package owners will use it as a reference when describing dependencies between packages.
  • Implementers will use it as a reference when implementing design classes.
  • Reviewers will use it as a reference when reviewing the software architecture, design model, and implementation model. This resolves a lot of debate regarding the quality of the artifacts produced.
  • Newcomers to the project will use it to understand what is being produced.

An important input when this document is created is a specification of the implementation environment. Examples of things that should be specified are target platform (hardware, operating system), window system, screens, development tools (language, GUI builder), database management system, and component libraries.

Brief Outline To top of page

1. Objectives

A brief description of the purpose of the Design Guidelines.

2. Scope

A brief description of what the Design Guidelines applies to; what is affected or influenced by this document.

3. References

A list of related or referenced documents.

4. General Design and Implementation Guidelines

This section describes the principles and strategies to be used while designing and implementing the system.

5. Database Design Guidelines

This section gives rules and recommendations for the database design.

6. Architectural Design Guidelines

This section gives rules and recommendations for software architecture design.

7. Programmer’s Guide

This section explains how to use the low-level mechanisms by showing the interface of each mechanism and explaining how to use it.

This section should also either provide or reference a language-specific style guide which presents rules and examples of good programming style.

Timing To top of page

Many of the decisions in the Design Guidelines should be developed before the project starts. During the project it should be continuously improved.

Responsibility To top of page

An Architect is responsible for producing the Design Guidelines document.

Tailoring To top of page

You should adjust the outline of the Design Guidelines document:

  • Some of the General Design and Implementation Guidelines may be irrelevant for your project.
  • You may need additional sections and appendices to describe how to handle any mechanisms that are not handled here.
  • The order of the various sections may vary, depending on the system's stakeholders and their focus or interest.

Annotated Outline To top of page

  1. Objectives

    This section defines the role or purpose of Design Guidelines, where it is situated in the overall project documentation, and briefly describes the structure of the document.

  2. Scope

    A brief description of what the Design Guidelines applies to; what is affected or influenced by this document.

  3. References

    This section lists the documents related to, or referenced by Design Guidelines. Eventually the section may be structured in subsections: external documents versus internal documents or government documents versus non-government documents and so on.

  4. General Design and Implementation Guidelines

    This section describes the principles and strategies to be used while designing and implementing the system. In most cases, you will need strategies for the following:

    1. Mapping from Design to Implementation

      You must specify how the design is mapped to the implementation; both at the package level and at the class level.

    2. Specifying Interfaces on Subsystems

      When you are developing the system from the top down, it is important to narrow the visible interfaces to the subsystems. This enables developers to change the parts of a subsystem that are not visible outside.

    3. Documenting Operations

      It is important that you decide on a standard way of describing operations. An operation consists of the name, the arguments, a brief description, and an implementation specification. Ask yourself the following questions when documenting operations.

      • Should all (formal) arguments be documented? It is suggested they should be, although experience shows that they might be difficult to maintain, because they are redundant with the code.
      • Should the argument type be documented? Generally it is suggested that it should be.
      • Should you use any naming convention for the operations in a class? For example, in C++ you might choose to prefix private and public operations in different ways. This makes the operations easier to understand.
    4. Documenting Messages

      It is suggested that you not document all the actual parameters in the message. It is redundant with the code and might prove difficult to maintain.

    5. Detecting, Handling and Reporting Faults

      You must have a strategy for fault management. Your strategy depends to a large degree on which programming language you have chosen. Many languages feature fault-management support, such as Ada "exceptions." The fault-management strategy you choose will influence behavior in the design objects. For example, you must decide whether to use status parameters in each operation that tell if the operation has succeeded, or to let the object raise an "exception," as in Ada.

      If necessary, you can apply different fault-management strategies to different parts of a system. The important thing is that you have at least one strategy, and for all possible strategies, that it is clear when to use them.

    6. Memory Management

      Memory management means ensuring that memory is always available. This implies that you remove objects not referenced by any other object so that the memory they occupy can be used for new objects. How you solve this depends on the implementation language. In some systems it will be automatically solved, for example, by a garbage collector; but in others you must carry out the memory management yourself in the programming language. In other words, you will have to define when and how to clear any memory occupied by un-referenced objects.

    7. Software Distribution

      If you have a system that will be distributed among several physical nodes, its objects must also be distributed among the nodes. Before design starts, you should prepare this work by specifying general strategies for how objects should be distributed, and how to use the present inter-process communication technology. If the target environment is unfamiliar, it might prove useful to prototype solutions.

    8. How to Represent Reusable Components

      Before starting design, you must decide which reusable components, reusable component systems, libraries or "Commercial-Off-the-Shelf" (COTS) products to use. You must also decide if, and how these should be modeled in design.

    9. Designing Persistent Classes

      Ideally, the database-management system you choose, whether relational or object-based, should not affect the design model very much.   Persistence should be provided by a framework which makes persistence as transparent as possible.

      Most persistence design work focuses on identifying and resolving performance problems.   To make this easier, the following should be done:

      • Identify the lifecycle of each persistent object: when it will be created, read, updated and deleted within Use Case Realizations.
      • Identify transaction boundaries within Use Case Realizations.

      There is some iteration between Database Design and the design of persistent classes: depending on the database, some associations between design classes are either clumsy to support in the database, or create such a performance problem that some adaptation of the Design Model is necessary.

    10. Fault Management
    11. Transaction Management

      This section should discuss the strategies used to manage transactions, including how transaction management will be accomplished. The interaction of transaction management and Fault Management should be discussed, including how the system recovers from transaction failures or aborted transactions.

      If there are special restrictions imposed by the transaction management mechanism (such as MTS requiring 'stateless' objects) that affect the architecture of the system, they should be discussed here.

    12. Special Use of Language Features
    13. Program Structure
    14. Hardware Interfacing
  5. Database Design Guidelines

    This section gives rules and recommendations for the database design. The following topics should be discussed:

    • Mapping from persistence classes to database structures, including how to handle potential conflicts such as many-to-many associations in the design model and inheritance.
    • Mapping of design class attributes to database primitive data types.
    • Use of the Process View to describe the processes and inter-process communication used by the persistence mechanism.
    • Use of the Deployment View to describe the physical distribution of data across nodes.
    • Naming conventions for database structures (e.g. tables, stored , stored procedures, triggers, tablespaces, etc.)
  6. Architectural Design Guidelines

    This section gives rules and recommendations for software architecture design. They are organized around the different architectural views: Use-Case, Logical, Implementation, Process, and Deployment Views. The rules deal mostly with decomposition. For example, the Implementation View guidelines specify the rules for packaging modules into subsystems, layering subsystems, and so on. See also, the Software Architecture Document, section Analysis & Design.

  7. Programmer's Guide

    For each significant mechanism put in place in the low-level layers of the system, you should have a programmers' guide that shows the interface of the mechanism and explains how to use it. These include a user's guide of the timer mechanism, of the inter-process communication mechanism, of the recording mechanism, of the database-management system, and so on.

    In addition, this section should either provide or reference a language-specific style guide which presents rules and examples of good programming style.

 

Display Rational Unified Process using frames

 

© Rational Software Corporation 1998 Rational Unified Process 5.1 (build 43)