BACKGROUND
This assignment is a follow-on from Assignment 1, in which the goal was to design a Software Architecture for the OAM layer of the SX4 telephone switching system.
CONSTRAINTS FOR THIS TERM
The following constraints, previously given in assignment 1, still hold.
For this version of the course, the following constraints are imposed by the management:
GOAL
You are to produce a (web-readable) report that documents the Detailed Design of the software that you propose to develop for the SX4 system (for OAM in this term). Your target audience is to be a junior programmer who is to implement your design as well as a manager or developer who is somewhat but not intimately familiar with telephone switching. A junior programmer should be able to correctly implement any module given your Detailed Design.
Your report giving the Detailed Design for SX4 is to be a companion document to go with your report on the Architecture. Ideally, you will repeat little that was already given in your Architecture report. In the web-based version of your Detailed Design report, you should add links back to the relevant part of your web-based report on the Architecture. At the same time, your Detailed Design report should, as much as reasonable, be a standalone document that can be read without the Architecture report.
REPORT
You report should include the following:
Title: About 3 to 6 words making clear what your report is about.
Authors: List of authors, their addresses, date, etc.
Abstract: About 2/3 of a page overviewing the key points in your report, targeted to a programmer, developer or manager.
Introduction and Overview: About 1 to 3 pages summarizing the purpose of report, its organization, and its salient conclusions. A person should be able to read just the abstract or just the introduction and have a good idea what is in the rest 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 will include a clear description of the behaviour of the module and its externally visible interface. It will include a description of algorithms and data structures to be used and will give pseudo code when necessary to describe non-obvious implementation techniques.
In this version of the course, the implementation is to be in C, so a "module" will eventually be implemented as a set of files in the C language. In general, a module should consist of a dot-h file (giving the interface to the module) and a dot-c file (giving the implementation of the module). A subsystem is to be a set of modules and other systems.
You should reference (and link to) descriptions in your Architecture report of important abstractions, ADTs, data structures or algorithms that are critical to the successful implementation of your system. Use diagrams as needed for this report. You are to include a "dependency diagram", in which the boxes are modules and the 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, such as the Graphical User Interfaces, files, data bases, messages or networks. This should include menu design (give example menus) and an umambiguous 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.
Data Dictionary: Update the glossary in the Architecture report as necesary 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.
DOCUMENT STYLE AND LENGTH
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 25 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 next assignment, number 3, is to implement this Detailed Design. Each implemented module is to include as comments its specification (given in this Detailed Design 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 is to 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 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. [Actually, these are determined by the 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.