CS 4120: Introduction to Compilers Spring 2016

CS 4120: Overview Documentation for Programming Assignments

Some programming assignments must be accompanied by an overview document as described below.

Format

You should format an overview document as either ASCII text (with lines at most 80 characters long), HTML, or PDF. The filename must be overview.*, where * is the appropriate extension. Use good taste in formatting your document; the course staff values simplicity and readability over fancy graphic design. The typical length of an overview document should be two to four letter-sized pages, with 10–12 point font and reasonable margins. Use good judgment about what will be useful to the course staff while grading your assignment: incomplete and excessive documentation will both be penalized.

An overview document should be structured as described below. You may omit sections that you find to be irrelevant for your assignment. The suggested word length of each section is a guideline, not a requirement.

Metadata

• The programming assignment title—e.g., "Programming Assignment 1: Radio Recommender System"
• The names and netids of all students in the group submitting the assignment.
• The fully qualified class name of your main program and any other instructions needed to run the program.

Summary (50–300 words)

Summarize the most noteworthy aspects of the rest of your overview. Anything you mention here should be described in more detail later in the document. You might include:

• Which parts of the assignment were the most challenging.
• Interesting design decisions that you made.
• Major issues that you ran into while designing, implementing, or testing your program.
• Known problems with your implementation, such as missing functionality or bugs.

Specification (10–500 words)

Sometimes you will need to resolve ambiguities or inconsistencies in the assignment specification.

Describe your finished specification. Identify the choices you made in finishing the specification, and provide a rationale for them. It might be useful to discuss alternatives you considered, why you rejected them, and the tradeoffs involved in your ultimate choice. If you made any changes to the given specification, justify why a change was needed and why the result of your change is reasonable.

Your job is to convince the course staff that your finished specification is reasonable and in the spirit of the assignment. If you are not convincing, the staff may deduct points.

Design and Implementation (150–1000 words)

Discuss how you created a program that satisfies the assignment specification. This includes topics such as:

• Architecture:
  • Identify the important classes and packages that make up your design?
  • Show how classes are composed and interact to accomplish the design goals. A module dependency diagram is encouraged.
  • Present key interfaces provided by classes, and discuss any design patterns that you have used and why you chose to use them.
  • Discuss any important invariants maintained by classes.
• Code design:
  • Identify algorithms employed in your program. We encourage you to include high-level pseudocode of any complex algorithms that you use. We also encourage discussion of any boundary conditions or formulas involved, as well as citations for sources of your algorithms.
  • Describe data structures that are used.
  • Discuss any tradeoffs you made between different design goals, such as between simplicity of code and efficiency of execution.
• Programming:
  • Your implementation strategy—e.g., top-down, bottom-up, ..., and why you chose this strategy.
  • Any challenges you encountered while coding.
  • Any code reuse or revision you employed from previous assignments.
  • Which group members wrote which parts of the code.

Your job is to give the course staff enough information that we can understand your program, without needing to look at the source code, and to convince us that you thought carefully about the construction of your program.

Testing (150–1000 words)

Though the course staff may sometimes provide some test cases for you; it is almost always a mistake to think that those test cases are complete. The course staff often has a reserve of tricky test cases that your code will be tested against. Course staff tests are necessarily black-box tests that won't necessarily result in good code coverage. So spend time designing your own test cases. And don't wait until the last minute—do it early in the assignment, even before you've written any code.

Testing at the last minute is a recipe for failure. You should be testing your program incrementally as it is developed, starting as early as possible.

Describe and evaluate your test plan, and discuss any interesting issues that arose during the design of your test plan. Why do you have confidence that your test cases have enough coverage of the input space, and enough coverage of your code? Do your test cases accomplish both unit testing and integration testing? Include pointers to your tests.

Describe the results of carrying out your test plan on your program. Which of your test cases pass, and which fail? What systems did you test on (e.g., Windows, Linux, or Mac OS X). If any of your tests fail, be sure to include a discussion of why you think they fail in the known problems section.

Claimed test case results that cannot be reproduced with your submitted code will be severely penalized and might even be an academic integrity violation. Never "fix up" the output of your program.

Your job is to convince the course staff that you exercised due diligence in validating your program.

Work plan (20–100 words)

Explain how you divided up the work among the project team members, and in what order you plan to develop the various project components. Justify why this plan will minimize the risk of redesign and allow you to test incrementally and continuously during the development process. Identify any key dependencies between different implementation steps, where one team member cannot start an implementation task until another team member has completed their assigned task.

Known problems (1–500 words)

Detail any known problems with your specification, design, or implementation. Problems that are clearly identified and described here will be looked upon more favorably than problems that the course staff discovers on its own. Are there bugs in your program? Missing functionality? Incorrect specifications? Incorrect documentation in the code? Let us know.

Comments (1–200 words)

Express your opinions about the assignment. This section of the overview document will not be graded, but it earns good karma. We appreciate hearing your thoughts. You might address such questions as:

• How much time did you spend on the assignment? How was it divided between designing, coding, and testing?
• What advice should we have given you before you started?
• What was surprising about the assignment?
• What was hard about the assignment?
• What did you like or dislike about the assignment?
• What would you change about the assignment?