Introduction

It is, however, important for you to realize that one of the purposes of this course is to help you begin your preparation for a profession. If you are a major in Computer Science or Computer Engineering, you will find that your experience here will serve you well. Even if you never take another course in computing, you will have learned much about the kinds of techniques professionals use and especially about the courtesy that they are expected to show to others needing to read and understand their work.

The conventional scheme used in universities to assess a student's accomplishments is the grade. We therefore use a grading system to assess your success not only in writing a program that "works," but also in completing a project that meets the standards of professionalism we have set. Meeting these standards is neither especially difficult, nor especially burdensome in terms of your time.

We hope that you will realize that we are not just being bureaucratic, and that you will understand the benefits of what we are asking you to do. In any event, we are giving you, through the grading system, a tangible incentive to do it.

Project Grading

• 6 points, or 30%, are given for the correctness of your program as shown by the source listing and test run(s).
• 4 points, or 20%, are given for your Test Plan(s), in which you describe and justify the test cases you will use to test your program(s).
• 4 points, or 20%, are given for the structure and style of your program, including indentation, consistent capitalization, blank lines for readability, appropriate level of comments, etc.
• 6 points, or 30%, are given for your User Document(s), in which you describe to your potential user(s) the functioning of your program(s) or package(s).

Schedule

Many teachers refuse to accept late projects at all, but in this course you are permitted to turn in projects at any time. Your grade on the project will, however, be reduced by 4 points, or 20%, for each week it is late.

Note that if you are extremely busy, you can buy an additional week of time for a 4-point price. You do not need permission to do so; just turn it in late. The "lateness fee" will be waived only for documented medical situations or other unusual circumstances. "The computer was down" is not an unusual circumstance; our response will always be "the computer often goes down; you should have allowed yourself more time."

Project Preparation

1. Read the User Document(s) to see just what your project is promising to deliver.
2. Read the Test Plan(s) to see how you have planned to demonstrate that your project delivers on its promises.
3. Read the Test Output to see whether, indeed, the actual test followed the plan, and whether the program behaved as the test plan anticipated.
4. Read your listing files to assess the general quality and style of your code.

About User Documents

1. general-purpose, reusable software components, which Ada calls packages
2. end-user programs

Type 1

What should that person's user guide be?

The package specification (interface), complete with pre- and post-conditions, is a good start, isn't it? It lists all the methods (operations) syntactically, and the pre- and post-conditions describe the semantics of each method (operation). This interface file serves as the contract between the component developer and the client-program developer.

Should a user guide be more than this? Well, maybe there are some additional things you want to tell the programmer, but these can be brief annotations to the contract. The contract should not normally describe anything about the internals or implementation of the package. Indeed, in a business situation, in which you were selling or licensing your component to other developers, these details would often be considered confidential trade secrets! In any case, the client programmer should be able to learn how to use your component without knowing the details.

A Type 1 user guide can be a copy of the package interface, suitably annotated, and clearly marked User Guide for the Package <Name> (substitute the name here).

Type 2

HOW DO I USE THE PROGRAM?

Nothing more. Nothing about the packages, nothing about the internals. Just

• what can I do with this program?
• what happens if I do it correctly?
• what happens if I don't?

About Test Plans

Type 1

The main question you should ask yourself in starting to develop a test plan is "suppose I were going to spend a lot of money to buy this component for use in a critical system. What would I need to know about the component in order to be certain that the results I get from it are reliably correct? How can I have confidence that I am getting my money's worth?"

In testing a component, we need to answer these questions:

• Does each method (operation) work properly by itself?
• Are the results of the operations composable? That is, can we always use the result of one operation as an input to another operation?

For example, if you're testing an arithmetic operation for some new data type, can we validly use the result of an addition as the input to a multiplication? Are you sure? Have you tested this?

Another example: if you're testing an input/output component providing an operation that writes a structure to a file, and another that reads the same kind of structure from a file, can the read operation validly read a structure that the write operation wrote? Are you sure? Have you tested this?

Choosing tests completely at random will not necessarily test all these conditions. Make a table of test cases that will do so. In each case we indicate what the test values are, why we chose that particular test, and what we expect the result to be.

Type 2

Project Submission

We try to grade project carefully and thoroughly, to give you proper feedback and a fair grade. To help us do this, you must organize your project courteously, so the grader can read it in the order spelled out above. Accordingly, your submission must contain, in the following sequence:

1. A cover page, printed from a computer or neatly hand-written, giving your name, e-mail address, lab section, project number, and date submitted.
2. A copy of the project handout.
3. A table of contents (TOC) page, printed from a computer or neatly hand-written. The TOC must list each additional document or listing, in the sequence in which it is included. It is not necessary to number each page, only to give the various pieces in their proper sequence.
4. For each package you developed, completed, or modified in this project:
1. A user guide and test plan for the package, printed from a computer or neatly hand-written. The document must show, on the first page, your name, e-mail address, lab section, project number, date submitted).
2. One or more compile/link/execute scripts, according to the assignment sheet. Your test runs must show that the programs were executed according to your test plan.
3. Listing (.lss and .lsb) files, showing the package spec and body, any SEPARATE subunits, and any test programs you wrote or used to test the package.
5. For each end-user program you developed or modified in this project:
1. A user guide and test plan for the program, printed from a computer or neatly hand-written. The document must show, on the first page, your name, e-mail address, lab section, project number, date submitted).
2. One or more compile/link/execute scripts, according to the assignment sheet. Your test runs must show that the programs were executed according to your test plan.
3. The listing (.lsb) file for that program.

Do not submit listings for packages that were distributed to the class, and you just used without making any changes to them. On the other hand, if you are just using a distributed test program, submit a listing for it so the grader can see just what was tested.

Each program file must have, at the top of the listing, a "banner comment" in the following form:

---------------------------------------------------------------
-- Name: Danny Quayle
-- E-mail Address: dquayle@seas.gwu.edu
-- CSci 131-11
--
-- Project #1
-- Date: September 22, 1993
--
-- Brief Project Description:
--
-- This project simulates a game of ten-pin bowling.
-- A game is played by up to four players; a box score
-- is displayed after each frame.
--
-------------------------------------------------------------