Contents
Your design document is the complete description of your design -- anything that isn't here, isn't part of your design! Your design should fully explain all of the static and dynamic aspects of how you have divided responsibilities into classes, how these classes collaborate to carry out their responsibilities, and how this design implements the use cases in your SRS.
You have designed to a sufficient level of precision when you can answer "yes" to each of the following tests:
What follows are each of the sections that your SDS should contain.
Make sure to include all methods and all cardinalities, but do not include any of the attributes. Your class diagram should show all of the important responsibilities of each class. You may want to use TogetherSoft for drawing your class and other UML diagrams. If you do so, however, make sure to save these files as "html" and "jpg" or "gif" files. That is, ensure that you do not include any propriety formats as part of your project. We have copies of TogetherSoft available in the CSS labs (subject to your signing a "non-commercial use" agreement -- speak with Stephen Rondeau, our CSS system administrator), and you can also download a copy for your personal use, subject to a similar agreement. Please include this diagram inline in the document, rather than as an external hyperlink. Likewise for any of the other diagrams below.
Include one or more sequence diagrams illustrate the collaborations of your objects for only the Main Success Scenario of all of your Use Cases at the user goal level from the SRS. Make sure to include a hyperlink to each MSS from each of the appropriate sequence diagrams. You only need to include collaborations/messages that are public so as to reduce the complexity of your diagrams.
Your sequence diagram(s) should call most if not all of the methods of all of the classes listed as responsibilities in your class diagrams. Make sure to indicate which object creates which other object! You should have all object creations indicated in your sequence diagrams. Finally, you should indicate the types of all parameters passed and returned on the arrows of your diagrams.
The design should be sufficiently detailed so that you can "tell the story" or "run" the design in order to verify that it covers the MSS of your use cases, but not so detailed that it is difficult to follow what these diagrams are representing. Note that these will take a considerable amount of time and are completely non-trivial. Since much of your implementation will stem from these sequence diagrams, they are worth a bit of time investment. The bottom line on level of precision and detail is: can someone who is not a member of your group (such as me) understand your design? Does more detail help or obscure?
Please also include psuedo-code or an english description of the algorithm that each sequence diagram describes.
This is specified at 2 different levels of precision.
Hyperlink to a set of "html" files for all classes and methods, both private and public. Generate these html files from ".java" source files using the javadoc tool. Note: this does not mean that you need to have your source files implemented. Rather, it only means that you have your source files commented, but possibly without any code whatsoever. Note that if you use TogetherSoft or a similar tool, your java class files can be generated automatically from your class diagram.
Place all of your code files in a single package (named appropriately). Make a brief javadoc comment for the package, and hyperlink this javadoc comment to the requirements and design docs. Use the @see javadoc symbol for this purpose.
Each class and method should be commented using preconditions, postconditions, and invariants, using both Java's assertions and also the throwing of exceptions. You should follow the Java convention of making explicit checks and throwing exceptions for all preconditions to public methods, while preconditions to private methods should use assertions to check their truth value. Postconditions should be checked using assertions. These should be included during this hand-in, though these may need to be changed as you write the code.
Note that this style is similar though not identical to what Sun uses in commenting their API's. What is conspicuously missing from the Java API's is a clear statement of the preconditions and postconditions. Some of this information is encoded in the @return and @param flags, but not all of it. Also, class invariants are not all documented.
Also, for each class, provide the create date and the author in the javadoc comment.
Provide a text description that gives any additional information that you think someone else might need in order to fully understand your design. You should target this to another developer who would hypothetically join your project midway (e.g. such as now). What additional information does this person need in order to get up to speed on your design? It is not necessary to put into English the information you already have in one or more of your other sections -- just add new information not already obtainable in another form. Or summarize or emphasize important aspects of your design that may be difficult to understand, or where there might be ambiguity.