SOEN 6461 Software Design 101

Dr Greg Butler

This document is a brief overview of the object-oriented software design process.

Software Design 101

Design describes the "machine" in terms of its "parts", how parts are "connected", and how parts work together to achieve the overall task.

1. Plan.
   Understand the problem; in particular, know the required inputs and outputs, and the information they contain, and in what format.
   Gather examples of inputs and outputs, and understand how the outputs relate to the inputs.
   Describe the "parts" of the real-world represented in the inputs and outputs, and in the description of the problem. This is the problem domain model.
   Know which qualities are required for the design, such as correctness, performance, scaleability, etc.
   Specify the system to be designed as a black box; that is, use pre-conditions, post-conditions, and invariants to describe the required properties of the inputs and outputs, the conceptual states of the system, and their relationship to one another.
2. Do.
   The two main goals in design are
   1. to make the parts work together to achieve the qualities of the overall task; the designer looks at correctness first, and then looks at the non-functional qualities.
   2. to "structure" or organize the design so that it is understandable, and therefore other developers are able to debug, maintain and evolve the system.
   At the small scale, structure is provided by classes and objects. They bring together related data represented as attributes and behaviour represented as methods.
   At the large scale, a design is often divided into layers or as a hierarchy of subsystems.
   At both scales, you may use class hierarchies to organize a set of related classes in order to be clear about what they have in common, and to be clear how they differ from one another. Note that template classes (also called generic classes) perform a similar role in that the parameter captures how the set of classes differ, while the template class represents their commonality.

   You design your machine using your experience with best practice, that is, patterns, and your understanding of the problem obtained in 1. Plan above. The things that you consider as you select the parts of your design are the following:

   • Objects
     These are typically computer representations of the real-world parts in the problem domain model.
     They are organized into classes.
     You need to describe each object and class: give it a meaningful name; what is its purpose, role, function, responsibility in the design; and its behaviour.
     That is, answer the questions: What is it? Why is it there? What does it do?
   • Associations between things
     There is a link between two objects because of an association between their classes that "relates" the two objects. This can be due to several different types of associations. The common ones are:
     • data relations between the objects or their attributes as in database modeling;
     • work collaborations of the objects;
     • one object making use of another object's information, knowledge, or services; or
     • connections between objects such as use of interfaces, remote procedure call, http, TCP/IP protocols, messages, event notification middelware, etc.
   • Interfaces
     An interface collects together methods related to a set of services.
     An interface hides the internal representation of an object from the rest of the design.
     An interface may be an endpoint or port at one end of a connection between two objects.
     An interface makes an object into a black box.
     How do you describe the services offered by an interface in such a way that client objects know what to expect from the service object? Answer: Specify it with pre-conditions, post-conditions, and invariants to describe the required properties of the inputs and outputs, the conceptual states of the object, and their relationship to one another.
   • Collaborative behaviour amongst objects
     The design must go beyond simply describing each class and its interfaces. The design must describe how objects work collaboratively to achieve the overall task.
     This can be done using UML sequence diagram, UML collaboration diagram, UML activity diagram, or pseudocode for methods that coordinate the work.
3. Review.
   Hand execute your design on explicit scenarios to check that the design has the required qualities.
   Demonstrating correctness needs you to provide an argument (logical reasoning) that your design produces the correct output in all circumstances.
   Demonstrating efficient use of resources such as time, memory, or disk, requires you to provide formulas for the amount of resources used for a given size of input; or to provide an upper bound on the amount of resources used.
   Scaleability is demonstrated by showing that your formulas for resource use grow linearly (or less) as the size of the input grows.

Brainstorming Object-Oriented Detailed Design of Software

Sketch CRC (Class-Responsibility-Collaboration) for each class
UML diagram for system objects and their collaboration
Determine interfaces (that is, the operations) of each class
Specify contract for each operation
Select algorithms and data structures for each class
Describe algorithm for each major operation using UML note

Documenting Software Design for Assignments

Your design document should clearly follow the five required sections, by having clear headings:

1. Problem Description
   This includes a description of the functionality, as done in the document for the Design Assignments. It also includes a statement of each non-functional requirement that states the non-functional quality, and states a concrete requirement for that quality.
   It does not include introductory material to the problem, nor any design information.

2. Design Description
   For these kind of designs that have a main algorithm for a computational problem, a useful structure for this section is:
   1. a summary paragraph presenting an overview of the design: give the big picture, and mention major classes and methods;
   2. a class diagram for the whole design, including complete method signatures, with a title and caption for the diagram;
   3. the main algorithm as pseudocode: this can be a figure with title and caption, where the pseudocode is single-spaced, and can be in a smaller font, and properly indented;
   4. a description of each major class:
      1. class name, with responsibility/purpose/function/role clearly described;
      2. data attributes: name, type, description
      3. signature for each method, with pre- and post-conditions, and maybe a description of its purpose
      4. pseudocode implementations of major methods, if necessary.
   5. maybe, descriptions of behaviour using interaction diagrams, if necessary.
   
   You do not need CRC cards. CRC cards are used while brainstorming the design. Once you have the design, then describe the design using class diagrams and interaction diagrams. Many of you use these wrongly to include methods.

3. Major Design Decisions
   List the major choices you made and the impact they had on the design.

4. Design Review
   For correctness, you need an argument as to why your design produces the correct results. For these computational problems that requires you to clearly write an invariant (or several invariants) of the main algorithm, to show it is an invariant of the main algorithm, and to show that the invariant implies the results produced by the main algorithm are correct.
   It is not enough to simply repeat the trace of the scenario in the document for the Design Assignments.
   For most of you the reader would have no confidence that your design is correct: first, because the description of the design is unclear, and second, because there is no logical reasoning justifying that the design produces the correct results. You need a clear design description before you can reason logically.
   For usage of resources, you need explicit formulas for the amount of memory, and the amount of time (number of instruction steps).
   It is not enough to say: I reviewed this quality.
   It is not enough to repeat sentences from the document for the Design Assignments.

5. Glossary
   These should be dictionary-type entries for the terms important to your design, such as classes, methods, objects, data structures.
   Do not define terms from software engineering or OO design, such as CRC card, state, etc.

Common Problems in Assignment Documentation

Students do poorly in Section 2 Design Description. You need to start early, develop a design through several iterations. Then document your finished design.
Use classes and objects from the problem domain, rather than built-in types/classes like String, Character, int.
Indent examples of pseudocode properly.

Students do particularly poorly in Section 4 Design Review. You need a logical argument as to how and why your design satisfies the required quality attributes, including correctness.

Do not include a Problem Domain diagram or section in your document: that belongs in the requirements document, not the design document.

Learn to use Latex.