Specification Guidelines

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 algorithm. 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.

Specification Outline for Project 2

High Level Specifications

Overview

• What is the purpose of this application?
• What does it do?
• What is the application's utility? (Why should anyone use it?)

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

Modules

Notes: A module or component is some unit of program operation. For this 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

• Give a general overview of the path that your program will take from world initialization to game termination. Consider including a diagram.
• How do the modules described in the previous section interact here?

World Description File Input/Parsing

• What is the format of a valid world description file. Consider including an example.
• What information MUST be included in a world description file? Is there optional information?
• How will your program parse the file?
• How will you check for validity?
• What inputs constitute an error? How will you handle such input?

Game Initialization

• Provided a valid world description file as described in the previous section, how does your program use this input to initialize the game world?

Interaction with the User

• What commands can the user enter?
• What is the effect in the game world of each of these commands?
• How does your program parse the commands?
• How does your program detect an unknown command or an ambiguous command? What is the behavior of your progam in such a situation?
• What type of feedback is provided to the user for each type of command and for erroneous commands?

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

• Describe your class structure. How do you represent players, rooms, objects, etc? How do these classes interact with each other?
• Describe your algorithms for certain events in the game world. For example, what algorithm will you use for your thief to move around your world? How will your program determine when he will act and what item or items he will take?

Notes: Be specific here. Feel free to refer to actual classes and interfaces as well as their methods. Pseudo-code may even be appropriate. 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.

Analysis

• Run-time analysis
Time and space complexity

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.

Testing

• What sort of testing will you do?
• Describe your Unit Test suite.

Timetable

• In what order will you implement each portion of the specifications?
• How will the order you choose help you to debug each part, even though the whole program isn't yet complete?
• Create a timetable and try to stick to it.

Stylistic Notes

1. The specification is NOT a readme file. It is a technical document which should have correct grammar and spelling.
2. Examples are useful. It is often better to show with an example rather than to tell textually. Reusing one or two examples throughout the spec may make it easier for a reader to follow.
3. Being vague and wordy is not beneficial. Try to get your point across directly and briefly.

General Notes

• This project gives you a lot of freedeom to make design decisions. The questions posed in this document are only some of the things that you will need to consider. Your specification needs to detail ALL of your design decisions. I should be able to read your spec and implement your program without having any questions about design.

Examples

Return to spec