Specification Guidelines

(Originally written by Amanda Cruess for comp314 2006; last update 1/24/07)

Introduction

Your specs should document all your design decisions, as well as all the interesting points about your class structure and algorithms. Given a good specification, you (or anyone with commensurate programming experience) should be able to implement your entire program without running into any unforeseen design decisions.

However, after you submit your specs, you will inevitably run into unforeseen issues, or you will alter your algorithms. If this happens, you need to update your specifications to reflect the current implementation and design strategy. It would also be useful to note why such changes were needed. Be sure to submit updated specifications at each deadline.

If your spec differs from your code, both are wrong.

Turning in your spec

Formatting: Your spec must be turned in as either a PDF document or an HTML page. If you choose to use Microsoft Word to prepare your document, you must still generate a PDF version. (Windows users: install PDFCreator to enable printing to a PDF from any application. Mac users: This is built in to OS X.)

Subversion: You should keep your specification in svn like any other work you do in this course. Commit your working document files to the trunk (you can place them in a subdirectory, e.g. docs, if you like). When you are ready to turn your spec in, follow the tagging instructions to tag your trunk as tags/spec. As you complete your beta and final submissions, keep the spec up to date in trunk, and it will be copied along with your code when you turn in those milestones.

Anatomy of a Specification

The following guidelines are oriented around Project 1, ADVENTURE; your future specs will share many of these sections and borrow many concepts.

High Level Specifications

Overview

Notes: This need not be technically specific. This is something users should be able to read and consequently understand what the application does as well as why they would want to use it.

Program Use & Normal Behavior

Example:

Program Use & Normal Behavior

  1. The program will have a command line-based user interface. The user will need to type the following at a command shell:
    $ java Adventure inputfile
    where the inputfile is a world description file for a particular configuration of a game world.
  2. No output files will be generated. Program output will be sent to System.out.

Merits: Explicitly shows command line interface.

Faults: Should be more specific as to what a world description file is and what types of such files are supported. This may be discussed in more detail in another section of the specification, but that section should be referenced here. Depending on the context of this section, the numbering scheme may not be appropriate.

Modules

Notes: A module or component is some unit of program operation. For the Adventure project, initializing the game world with the world description file and parsing the input stream from the user's typed commands are two such modules (there are definitely more). For each module, you should describe operationally how it fits into the whole application, give a general overview of what the module needs to do and broadly detail how modules will interact.

General Flow

World Description File Input/Parsing

Game Initialization

Interaction with the User

Notes: You may feel like you are repeating parts of the project description here and in other places in your specification. This is okay. A project specification is a technical document that should be able to stand alone containing all the relevant information about your project.

Low Level Specifications

Data Structures and Algorithms

Notes: Be specific here. Feel free to refer to actual classes and interfaces as well as their methods. For all but the most trivial algorithms, Pseudo-code is almost always appropriate and examples are absolutely critical. The content in this section rests heavily on design choices, so the above questions should only be taken as a starting point. This is one of the most important parts of the spec for this project. Describe any abstraction you choose to implement and justify why this will allow you to add additional program features later. Include some discussion of why. Why did you choose the structure and algorithms that you did?

Analysis

Notes: Both analyses need not be rigorous, but should give an idea of how your program scales and which components, if any, are the bottlenecks. Include a discussion of alternative implementations you considered (i.e. Sets vs Lists), and why you ended up chosing the approach you did.

Testing

Describe your test plan:

Timetable

  1. Break up your project (design, prototyping, implementation, testing, etc.) into fine-grained tasks. A task like "Implement world parser" is so broad that you can't possibly schedule it; most likely you haven't even thought the task through yet to understand what will be involved.

    A well-crafted task is:

    • one that you think will take between an hour and a day or two
    • one that has clear termination criteria (i.e., you know when it's done)

  2. Assign each task to one or both of you.
  3. Estimate how long each small task will take. Leave columns for "Estimate", "Actual", and "Remaining"; we will want to know how accurate your estimates were. Maintain the original estimate for duration in Estimate, and the estimated work remaining as "Remaining"
  4. We repeat: You are required to keep the "Actual" column up-to-date. This will benefit you in the long run, because the only way to get better at making good estimates is to review how well your previous estimates held up.
  5. Leave some time in your timetable for bug fixing, spec updating, regression testing, and so on.

Stylistic Notes

General Notes