(Originally written by Amanda Cruess for comp314 2006; last update 1/24/07)
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
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
- What is the purpose of this application?
- What does it do?
- What is the application's utility? (Why should anyone use it?)
Program Use & Normal Behavior
- How will a user invoke your program?
- What kinds of input will it take?
- What kinds of output will it generate?
Program Use & Normal Behavior
- The program will have a command line-based user interface. The user will need to type the following at a command shell:$ java Adventure inputfilewhere the inputfile is a world description file for a particular configuration of a game world.
- 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.
- Describe components of architecture/modules.
- What are the interfaces between the 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.
- 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?
- 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. 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?
- 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. Include a discussion of alternative implementations you considered (i.e. Sets vs Lists), and why you ended up chosing the approach you did.
Describe your test plan:
- What kinds of unit tests do you intend to write? (You probably won't know your exact API yet, so you can't plan this exactly, but give a general idea.)
- What functional tests should be run on your program? Functional tests don't examine individual APIs or procedures or algorithms: They represent overall testing of compliance with the requirements. Think of it this way: If your program passes its functional tests, it has completed the “contract” set out in the assignment.
- Other kinds of tests or analyses you intend to run. Performance testing, code coverage, other automated testing tools.
- 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)
- Assign each task to one or both of you.
- 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"
- 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.
- Leave some time in your timetable for bug fixing, spec updating, regression testing, and so on.
- The specification is NOT a readme file. It is a technical document which should have correct grammar and spelling.
- 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.
- Being vague and wordy is not beneficial. Try to get your point across directly and briefly.
- 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.