CS 482 Final Report 18 Apr. Your final written report for CS 482 should follow the following set of software engineering guidelines. Your report need not contain each section of each report but must contain a majority of them and must contain each of the six parts. Feel free to send me email or see me in S103g for questions or concerns. The report must include technical details in the design section, which should be the longest section. It must communicate concepts of computer science well. -------------------------------------------------------------------------------- Software Engineering Document Templates This document contains templates for six software engineering documents. The source is http://frakes.cs.vt.edu/apxC.html Concept Exploration Document Requirements Document Design Document Test Document Source Code Project Summary Document -------------------------------------------------------------------------------- Concept Exploration Document Problem Definition Describe the problem to be solved by the projected system. System Justification Justify a computerized solution to the problem, explaining why the product should be provided. Justify the need to build rather than buy a system. User Characteristics Profile the user population for the product. This profile might include the size of the potential user population (important for assessing feasibility), the skill level (important for user interface design), the importance of the problems the product will solve to the user population, and so on. Features and Functions Sketch the major features and functions of the projected system, explaining how they fit together to provide a useful product for the target user population. Goals for System and Project Describe the projected effects that the product and the development project will have on its user population, the user organization, the developers, and the development organization. For example, a goal for the system might be to cut the time spent on some task by users in half; a goal for the project might be to assess a new design method. Constraints on System and Project State the financial, environmental, and political constraints on the system and project. For example, the system might need to be priced under $100 to be competitive. Development, Operation, and Maintenance Environment Describe the target environment, and the environment needed to develop and maintain the product. Solution Strategy Outline the steps to be taken to settle any further questions about feasibility, to generate requirements, to develop the product, and to deploy and maintain the product. Feasibility Analysis Demonstrate that the system is both technologically and politically feasible. Project Deliverables Provide an introductory paragraph listing the deliverables to the client for this project. For example, list all the project documents by name and the software source code. -------------------------------------------------------------------------------- Requirements Document Product Overview Describe the major functions and components of the system in general terms. Summarize the rationale for building the system. Development, Operation and Maintenance Environments Describe the hardware and software resources and tools necessary to build and maintain the product. Indicate the target hardware and software environment, including the optimal and minimal configurations for use of the product. Conceptual Model Present the conceptual model of the system (a high-level view showing the major services or components of the model and their relationships with each other). Graphical notations are usually preferred for this task, but other mechanisms such as clear English, decision tables, grammars, and so on may be used. User Interface Specifications Describe screens, windows, graphics, and other visual aspects of the system. State key bindings (that is, explain what each keystroke does). Specify the interaction or dialog conventions governing the interface. Functional Requirements Describe the services, operations, and data transformations provided by the system. This portion of the requirements document is usually the largest, because all functionality of the system must be described carefully, precisely, and in full detail. A variety of formal methods and notations may be employed for this purpose. Nonfunctional Requirements State the constraints under which the software must operate. Typical nonfunctional requirements have to do with efficiency, reliability, portability, memory size constraints, quality standards, response time, problem size, and so on. External Interfaces and Database Requirements If the system must interface with other systems, describe its interfaces to the external systems. Describe the logical organization of databases used by the system. Exception Handling Indicate the anticipated exceptional conditions and error conditions, and responses to these conditions. Foreseeable Modifications and Enhancements State any foreseeable modifications and enhancements for the benefit of the designers and implementors, who must take this information into account in their work. Such changes generally involve anticipated alterations owing to hardware evolution, changing user needs, the introduction of other systems in the operating environment, and so on. Design Hints and Guidelines State any design features, constraints, or pitfalls obvious at this time for the benefit of the designers and implementors. Glossary Define all software engineering technical terms for the benefit of customers, and all application technical terms for the benefit of the software engineers. -------------------------------------------------------------------------------- Design Document Template Design Overview Provide a high-level description of the system's structure with a small collection of top-level modules. This description should identify each major module by name, state its purpose, and discuss how it interacts with other modules. Architectural Model Present the system's architectural model; an architectural model of a system is a description of the top-level modules, and the data and control flow between them. Graphical notations are preferred for this task, but concise, well-written text may suffice. A class diagram is an architectural model for an object oriented project. Module Descriptions A module is any part or subsystem of a larger system. A module may itself be decomposable into other modules that each provide part of the parent module's functionality and hide some of the parent module's secrets. A module decomposable into other modules is called an internal module; a module that is not decomposable into other modules is called a leaf module. Internal modules tend not to have internal computational structure, serving instead as grouping mechanisms for their component modules. Leaf modules, conversely, have a rich internal computational structure. Certain information must be supplied for every module in a module description, but some information is only needed to document the richer internal structure of leaf modules. Information that should be provided for every modules includes the following: Module behavior. Explanation of a module's behavior includes (1) a catalog of the operations it provides, with descriptions of their input and output and their externally visible effects, and (2) a catalog of the data types and objects that the module provides. Assumptions. A module's assumptions are the conditions that must be satisfied for an implementation of the module to work. For example, a file processing module might assume that a file passed to it is open and readable. Secrets. The implementation details hidden from other modules inside the module under discussion must be listed. Constraints and limitations. The constraints and limitations governing implementation of the module, such as performance requirements, maximum memory usage requirements, numerical accuracy requirements, and so on, must be stated. Error handling. Errors and exceptional conditions that may be encountered by the module must be listed, along with their causes, and the strategy used to handle them. Expected changes. Any changes expected by the designers of the module are listed, with ideas about how the changes might be made. Related requirements. Reference should be made to the requirements satisfied by the module to help trace requirements through the design to the code. In addition to this information, leaf modules descriptions should also include the following: Module packaging. All invokable functions provided by the module should be listed, with their types, and the types of all their input and output parameters. The externally visible effects of each function should be explained, and any side-effects noted and explained. The salient features of any data types and objects provided by the module should be discussed in detail. Internal structure . Hidden data types and objects should be listed and their use explained. Internal functions should be listed with their types, the types of their parameters, and their effects. If particular sorts of algorithms are supposed to be used to implement some function, this should be stated and justified. If some algorithm is particularly crucial or tricky, it may be written down in pseudo code. A module is a class or a package in an object oriented project. Uses Relationships A module uses another module if some function provided by the latter is called somewhere in the implementation of the former. Uses relationships are important because they show the modules on which each module depends for its correctness. Rationale This section explanation design decisions, listing the alternatives explored, and justifying the design decisions that were made. Glossary As in other development documents, a glossary should be provided to minimize confusion about technical terms. The system design describes the structure of the solution to the problem given in the requirements specification. The solution is described in terms of the algorithms used to solve the problem, not in terms of how those algorithms are implemented. As usual, however, if the customer has implementation-specific requirements, they should be reflected in the system design. If your project includes a database then describe the normalization of the tables in your database. -------------------------------------------------------------------------------- System Test Document Template Test Plan Introduction - Summarize the software items and features to be tested. Test items - A description of the items under test. Features to be tested - A precise yet economical identification of all the features and combinations of features to be tested. Approach - Identify the major activities, methods, and tools that are to be used during testing. Test tasks - Identify test preparations, execution, and dependencies. Test Case Specification - One per test case. Test Procedure - One per test. Purpose - A description of what this procedure tests. Results - How the test was run and what happened. -------------------------------------------------------------------------------- Source Code Naming Standards Provide a description of the naming standards that your team will use for the design and implementation of the software. This section should include the rules that you agree upon regarding any of the following: File Name Styles (e.g. InitializeTheSystem.c versus SysInit.c) File Name Length (e.g. long file names versus DOS's 8+3 style) Function Names (e.g. is each name a Verb-Noun style?) Header Names Global Data names Local Data names Coding Standards Provide a detailed description here of your coding standards. A sample follows. Each function shall have a prototype. Each function prototype shall be listed in a header file. Only source code files (*.cpp files, not *.h files) shall include header files. Functions shall not exceed 100 lines. Each variable shall have a comment describing the variable's purpose. A consistent indentation of 4 spaces shall be used for each block. Comments shall be written at the level of intent (say why and what, not how). Each function shall have a header block describing the function name, purpose, each argument (input or output and purpose), the function's return value, side effects, and assumptions. ... Source Code Include working source code. -------------------------------------------------------------------------------- Project Summary Document Product Description Outline the system that was the goal of the development project, emphasizing features salient to the rest of the discussion. Current Project Status and Future Plans Discuss the current status of the project. Initial Expectations and Actual Progress Summarize the initial estimates of effort, personnel, development time, system size, required resources, target environment, cost, and so on. Contrast this with the actual effort, personnel, development time, and so forth. Mention parts of the system that were expected to be particularly troublesome that turned out to be easy, or parts that were expected to be easy that turned out to be difficult. Retrospective Schedule Present a timeline indicating the progress of the development effort over time. Successful and Unsuccessful Project Aspects Discuss the most successful aspects of the development effort and why they were important. List the most serious failures during the development effort and why they were important. Lessons Learned Based on the previous discussions, draw conclusions about what to do and not to do during product development. These will typically be both managerial and technical lessons. Recommendation for Further Projects Make any suggestions that others might find helpful in later development projects. --------------------------------------------------------------------------------