An important goal of 6.170 is to give you "real world" programming experience. The class is designed to teach you a methodology that makes it easier to keep your programs maintainable, understandable, and correct. We want you to approach a problem set as if you were building a commercial product.

When you write up your problem set, pretend that you are writing a description of your product for a potential customer (who will be, in this case, your TA). The document should be entirely self contained. So, this document needs to do several things. It needs to tell what your program does. It needs to explain how your program is designed and constructed. It needs to prove that your program works correctly and fulfills its specifications. And, perhaps most importantly, it needs to assure the customer that you have actually implemented what they asked for.

The following format serves as a general outline of what you should include in your write up. Remember that the quality of your documentation will count for a significant portion of your grade.

This section should give the customer an understanding of how your program works. This includes the human interface to your program as well as a description of what your program does. This section is basically the material that would be included in an end-user manual for your program. This section should, therefore, be designed for someone who wishes to use the program but is not knowledgeable of the particular design issues involved in implementing the program. It should answer the following questions:

1. What are the requirement specifications of the program (operations that the user can perform)? This should include command line arguments if there are any.
2. What is the Data Model for your program (include both graphical and textual description)?

In this section, you should explain any changes that you made to the original problem. Changes come in two varieties: clarifications and alterations.

• Clarifications are changes that more clearly specify anything that was confusing, ambiguous, or unclear in the original problem specification.
• Alterations are changes that involve the actual modification of the original problem specification due to implementation and design issues.

The problem set may leave issues confusing or ambiguous. Don't feel hesitant about adding clarifications to your documentation. We will be looking there to see how you have resolved these omissions. For every clarification or alteration you should clearly specify how you resolved the problem and why you resolved it in that particular manner. The reason for a choice is very frequently more important than the actual statement of a change. Frequently, attempting to write this section may lead you to discuss some of these issues with your customer. If there are ambiguities, you will want to resolve them in a manner that is consistent with the product the customer has hired you to create. Improper analysis of the customer's needs will likely lead to a product that is not what the customer wants; this tends to make the customer unhappy.

Keep in mind during this section and the ones that follow that the customer in this class is a strange variety of customer, namely a TA. TAs know the problems that you are trying to solve, and the techniques that you are likely to use to solve them. It is not necessary to repeat information in this section, or the others below, that it is obvious the customer already knows. Just describe the actual changes involved without reiterating everything that has already been stated.

This section should give the customer a feel for the overall design of your program. In this section describing the reasoning behind choices, such as your statement of tradeoffs and alternatives, and why you chose what you chose is at least as important as describing what you produced. You should describe what abstractions you used and why you chose them over possible alternatives. In addition to descriptions of significant modules, this section should give a clear indication of how these modules interface with each other using Module Dependency Diagram.

Please note that in this section you don't need to include complete specifications, as those should be provided in an appendix.

In this section, you should guide us through interesting details of your implementation. You should include a brief description of your representation, an abstraction function, and a representation invariant at the beginning of each data abstraction in your code (as described in section Appendix2). In this section you should concentrate on the following questions:

1. Do you have any unusual representations? How do they work?
2. Why did you choose the representations you chose over possible alternatives? What tradeoffs did you make?
3. If you used unusual, or otherwise interesting algorithms, why did you chose these algorithms? (You don't need to explain how they work in great depth, if you provide a reference to the algorithm's source. If you invented the algorithm then you should give a short description of the algorithm and why it works.)

You need to tell the customer how you showed that your program is correct. We want you to describe your testing strategy in this section, and not just list test cases. The description of test case categories and the reasoning about why these tests are adequate to show the program works are the most important parts of this section. This section should answer the following questions:

1. What was your general plan; i.e., in what order did you perform your tests? Top-down? Bottom-up? Module? Integration?
2. We require that you automate as much of the testing process as possible. A program that runs a predefined sequence of tests on the program being tested and checks the acceptability of the results is called a test driver (see section 10.8 of the course notes for a more detailed explanation of a test driver). Most of the time, you will use test drivers for regression testing. But did you use testing stubs? If yes, then why and how?

A complete description of all formats used should be given here. This may include file formats, data exchange format for communication between modules, between programs, or across a network. Include all graphs and figures (such as those explaining algorithms or data layout) that have not been embedded in their appropriate sections. All formats, graphs, and figures in this section should be individually named and numbered so they may easily be referred to in the rest of the document.

If there is code in the project other than your own, such as that provided by us, don't include it here. Only include the code that you actually produced. If you were required to change some provided code, only provide copies of the sections that you altered. Within your code, we expect to see the following things:

1. A specification for every abstraction in your program.
2. For every class, there must be an overview, a brief description of a representation, an abstraction function, and a rep invariant at the beginning of the class. These don't need to be phrased formally or mathematically, but they do need to be correct. Informal English descriptions of rep invariants and abstraction functions are perfectly acceptable.
3. Comments that clarify what's happening in your code, but don't just paraphrase the code.

Code should be organized such that all significant modules appear first followed by support modules. This allows the reader to examine the more important modules without having to wade through the entire code printout looking for them. This becomes especially important as the problem sets become larger.