Full size, professional programs require at least three documents. These are the Program Design Document, the User's Manual and the Technical Reference Manual. In this course, you should combine these documents into a single report, since your programs will be relatively short and simple. Your report should contain the following sections:
Cover Page -
Lists the course and assignment numbers, your name, my name, due date and submission date.
Introduction -
Describes what the program does. Restates the problem.
Operating Instructions -
Explains how to run (not compile!) the program. This section serves as the User's Manual.
Input/Output Description -
Describes the input required by the program (if any) and the output it produces. Include descriptions of all values that must be entered during program execution, the format of any input and output data files (not your source files) and the units of all values having units.
Description of Algorithm -
This should be a complete description of the algorithm. This description should include prose plus pseudo-code and a flowchart. This section serves as the Design and Technical Reference documents.
Sample Solutions and Test Results -
These are solutions to the problem using some method other than the computer program. They are often done by hand, but could include experimental or other results. Sometimes they are solutions for some special cases of the problem that are particularly easy (or at least possible) to solve by hand. These results should be explicitly compared to those from the program to demonstrate that the program works. The number of specific cases done should be sufficient to prove beyond a reasonable doubt that the program works.
Program Listing -
The complete source code (.cpp) files and header (.h) files, if any. Remember to include plenty of comments in your source code.
Data Listings (if any)-
Input and output data files as appropriate. Output data may be in the form of screen output captured from your PC (use Fn PrtSc on most laptops) or pasted into your report document by selecting and copying text from the DOS box (console window) using the dashed selection box icon.
Build Log (CS-150 only)-
This html document is generated by Visual Studio during the compilation and linking of a project (program). It is placed in the project folder and has the same name as the project with the extension .plg. It is best viewed and printed using M.S. Word or a web browser. This file should be included in your report without any modifications.
Your documentation should be neatly prepared and be in a plastic binder with a clear cover. Your folders will be returned after grading.
The following information must appear in your programs. Also see my modified version of Horstmann's Style Guide.
a) Program Header - The program header introduces your program. It should be formatted as follows:
/***************************************************************Program or Function Name: xxxxxVersion: x.yLast Revised: mm/dd/yyFilename: (of this source code file)Student (or Programmer): (Your name goes here)Course and Assignment Numbers: CS-150 Program z (A brief description of what this program does and how it does it. Include information about data file names and formats, program limitations, etc.) (revision history if any) ***************************************************************/ // Variables: (A complete list of the variables used in the// program and their meanings. Include types and units (feet, kg,// W, dollars, etc.) of all variables having units. For example,)// These comments can be collected near the top of your program or// distributed throughout the code just before each variable is// declared. double Engine; // Size of engine in Cu.In.'sint Max_Speed; // Maximum speed in RPM.b) Other Comments - Your program must contain enough comments to make its operation easy to understand. Every major section of code should begin with a block of comment lines explaining what the section does. You can generally identify major parts of your program by looking at the early versions of the pseudo code you wrote while designing it. You did start with pseudo code right? Comments may also be needed on the same line as particularly important statements. For example,
// Get user input ... cin >> Make, Model, Year // Get information about the car ...c) Other Documentation - A logical program design, consistent indentation and mnemonic variable, class and function names go a long way toward creating a well documented a program and will be considered in the grading.
Send
comments and suggestions about these requirements to: Dr. Charles S. Tritt
This page last updated 9/24/02