Author: Ric Holt, Department of Computer Science, University of Waterloo
Modified by: Grant Weddell, Department of Computer Science, University of Waterloo
Modified by: Ian Davis, Department of Computer Science, University of Waterloo

(hard copy due in class on Nov 2^nd, 1999)

CONSTRAINTS FOR THIS TERM

The following constraints are imposed by the management:

• (1) Implementation is to be done in C or C++.
• (2) All documentation (including the solution to each assignment) is to be web-readable, eg, in HTML (or other form readable from the web). At the same time, your report must be printable (you are to turn in a hard copy of your report for marking).
• (3) You were to work individually on the first assignment, and in teams of three to four for this and the remaining assignments.

GOAL

You are to produce a (web-readable) report that documents a detailed design of the software that you propose to develop for either the OAM or CU components of the SX4 system. Your target audience is a junior programmer who is to implement your design as well as a manager or developer who is familiar with telephone switching and with software architecture. A junior programmer should be able to correctly implement any module given your detailed design.

REPORT

Your report should be an expansion of an architectural design that includes the following additional information:

Authors: List of all authors, their email address, the date, etc.

Abstract: About a page that expands on an overview of the key points in your design, targeted to a programmer, developer or manager.

Introduction and Overview: Again, about 1 to 3 pages that give a summary of your more in depth report, its organization, and its salient conclusions. A person should be able to read the abstract and introduction and have a good idea of the contents of the remainder of your report.

Detailed Design:

You are to give, for each module, a clear specification for the module, such that a junior programmer can implement that module. The detailed design should include a clear description of the behavior of the module and its externally visible interface. It should include a description of algorithms and data structures to be used and will give pseudo code when necessary to describe non-obvious implementation techniques.

A "module" will eventually be implemented as a set of files. In general, a module should consist of a header (dot-h) file (giving the interface to the module) and a source (dot-c[pp]) file (giving the implementation of the module). A subsystem is to be a set of modules and other systems.

You should include appropriate references to the earlier architectural components of the report that concern important abstractions, ADTs, data structures or algorithms that are critical to the successful implementation of your system. Use diagrams as needed for this section, which should include a "dependency diagram", in which boxes are modules and arrows are dependencies. (A dependency from module M to N could be due to a call from a procedure in M to one in N, or a reference from inside M to a variable in N, etc.) These diagrams can be created using any method you choose.

External Interfaces:

Give details of information transmitted to/from the system, including user interfaces, files, data bases, messages or networks. This should include menu design (give example menus) and an unambiguous specification of any details by which modules in the system transmit information to/from the external interfaces. If appropriate, give C struct and function headers to specify these methods. (You do not need to include a discussion of feasibility studies.)

Integration Task Plan:

Give a design for a selection of integration tasks for your modules. An integration task description should include a test plan that outlines the selection of test data and test runs. In addition, you should include an integration task priority chart and a module/integration task matrix.

Cost Estimates and Task Schedule:

Give a design for a selection of coding and unit testing tasks. A cost/duration estimates table, schedule priority chart, CPM graph and Gantt chart should follow in this section. (Relevant tasks should include both coding and unit testing tasks and integration tasks.)

Data Dictionary: Update the glossary as necessary to include any new terms you have defined.

Programming Conventions: List programming conventions that your programmers are required to follow, including conventions for naming procedures and variables.

References: List any documents that your reader may wish to or need to read in conjunction with your report. Since the report is to be web readable, include links to references when appropriate.

Do not make your report longer than necessary. In general, shorter reports that contain appropriate information are preferred. Your report must not be longer than 50 pages (in the hard copy version), including all diagrams and appendices.

Write clearly. Organize your report so it is easy to find things in it.

Design to minimize the need for documentation (while maximizing the simplicity and understandability of your system), without sacrificing necessary system performance.

FUTURE ASSIGNMENTS

The third assignment will be to implement your detailed design. Each implemented module is to include as comments its specification (given in this report). Write your report such that it is a mechanical process (or nearly so) to extract these specifications from the report and to make them part of your C program.

In particular, each module (its dot-h file) is to begin with a comment that is the module specification, and each externally visible identifier of the module is to be commented by its description as given in this report. These comments in turn should be designed so that they (and the items they define) can be mechanically extracted from the code. (This extraction will be part of assignment 4.)

APPENDIX ON PROGRAMMING STYLE

You are to give the programming style to be used in your system. Your programming style guide should include the constraints listed in the following lines:

A module consists of a .c[pp] and .h file A module must only be accessed by means of its .h file.

Pick short clear names, possibly clear abbreviations, for each module's name. (These are determined by your detailed design.)

Identifiers in a module that are to be externally visible (exported) from a module must be prefixed by the name of the module, eg, scan_start for the "start" function in the "scan" module.

Violations of programming style are allowed, given an accompanying description of why the violation is appropriate.

Programs are to be written so that the need for comments is minimized. At the same time, comments should be used to make your programs very easy to understand.