Handout A8: Final Project Grading, Deliverables, and Schedule

Contents:

• Schedule
• Grading
• Deliverables
• Weekly Meetings with TA
• Further Information
  • Turn in

Schedule

You'll do your project in phases, with the following milestones:

In addition, there will be weekly meetings with your TA between Nov 1 and Dec 7, with a progress document due at each.

Grading

You will work in teams of three or four. Each team member should be responsible for a significant part of the design, documentation, code and testing. Each team will receive a single grade for the final project, determined approximately as follows:

Each stage of this assignment should be committed to CVS by 5:00 PM on its due date.

Deliverables

Here is what each of the deliverables should contain:

Preliminary design document:

Includes basic decomposition, rationale (succinct informal narrative explaining why certain design decisions were made, and what alternatives were considered and rejected); and work allocation and milestones (how tasks will be divided amongst team members, and the dates on which tasks are expected to be completed). You should also include sketches of what your GUI will look like (if you draw by hand, make arrangements with your TA for turning that sketch in).It should be possible to read the document linearly, so you should minimize the use of forward references, and should provide enough overview and explanatory material to make the design artifacts comprehensible. The purpose in preparing the preliminary design is to identify and explore important issues, so the document will be judged on how well it does this, rather than on the quality of the design per se.

You should express your preliminary design in under 15 pages. Your document will be a subset of that described in the Documenting a Software System handout. You should include all parts, including your testing strategy and a reflection of your experience so far.

The preliminary design should also include a project plan, which lists milestones for the team and allocation of tasks to each team member. A milestone is what you expect to be done by some date, such as a tested module or a working feature -- an achievement that is objective, easy to evaluate, and significant. There must be at least two milestones in the project between the preliminary design and the final deadline. The division of labor should be equitable. (It is most useful to combine the milestones and the task allocation into a single table with task, who, and when columns, rather than making the milestones and task allocation into to separate documents which cannot be easily related.)

Final design document:

Includes basic decomposition, rationale (succinct informal narrative explaining why certain design decisions were made, and what alternatives were considered and rejected); a brief description of your strategy for testing and validation; and a post mortem (a discussion of which design decisions turned out well, and which turned out badly, and why; whether the milestones were met, and what you did when they were not). Any changes between the preliminary and final design should be noted and explained.

It should be possible for you to describe your implementation and critique your design in under 20 pages (except for the Specifications, which may take another 5-10 pages and should be placed in an appendix). Conciseness is important. You should not include a printout of your code in your design document. Use the Documenting a Software System handout as a guide.

The final report includes a section on Design Changes. Detail what changes you have made to the design that described in your preliminary design document. Be precise. It is vitally important that your TA have versions of the descriptive parts of the Revised Specification, Implementation Overview, and Validation Strategy that accurately describe your submitted code and what you actually did for testing or validation.

User manual:

A standard user manual, intended for users not familiar with any of the course material. The better the design of the user interface of your client, the less you will need to explain in the user manual.

Specifications:

Every public method should have at least a minimal Javadoc specification. A careful pre-post specification should be written for any subtle or important method.

Unit tests:

Each test should have a brief comment explaining its purpose.

Preliminary Source code:

Will be judged by its correctness, clarity of structure, and the judicious use of runtime assertions and representation invariants.

Final Source Code:

Will be judged by its correctness, clarity of structure, and the judicious use of runtime assertions and representation invariants. You will also need to package your application using the Java Web Start (JAWS) tool. See the Final Project Tools handout for more information on JAWS.

Weekly Meetings with TA

Each team will meet with its TA once a week for a half-hour. You should contact your TA to schedule these meetings; one convenient time might be during the 1pm-2pm slot reserved for lectures. To receive full participation credit:

• All team members must be present at all meetings.
• All team members must answer questions and participate in the discussion at each meeting.
• A clear progress document that is useful for productive discussions must be handed in each week at the meeting. At the first meeting a draft of the Preliminary Design will serve as the progress document.

Although the progress document must be clear, it is short and informal. This document will form the basis of discussion during the meeting, and the TA will keep it on file as a record of progress made. The team should bring multiple copies to the meeting, one for each team member and one for the TA. This progress document should include the following information:

• A description of all the new issues that have been discovered during the previous week. This includes both a list of newly discovered bugs, and a list of unresolved design issues.
• A description of all the issues that have been solved over the past week. This includes a list of bugs that were fixed, and how they were fixed, and a list of design issues that were resolved, and how they were resolved.
• A list of all the issues from previous weeks that are still unresolved.
• A plan for the next week, with specific actions and goals for each team member.
• An assessment of success at meeting the previous week's plan.
• As an appendix: a change log for your group repository. This should be automatically generated from the commit messages in your version control system. Create a change log from your CVS archives using the following Athena commands:

  % cd a-checked-out-version-of-your-project
  % rcs2log -r "-d >=2007-04-10" > ChangeLog
  

  where "2007-04-10" is replaced by the date of your last weekly progress meeting. You can also use the cvs2cl script. If you are using subversion as your version control system, then use svn log or svn2cl to generate your changelogs.

  We will not be looking at your change log to measure progress; we will be looking only for good version control discipline: small, atomic commits with meaningful commit messages.

• The document may also contain any other material that you feel describes your progress, such as MDD fragments showing changes to the design.

Further Information

• The work you hand in for the preliminary design and release should differ from that of the final release in its state of completeness, not in its quality. It's very important to get into the habit of working methodically. If you just hack like mad, and hope to make your code clean and elegant at the end, you won't succeed.
• Your TA will judge the usability and correctness of your client during demos after the preliminary release and at the end of term. You are responsible for scheduling this meeting with your TA. All team members must be present to give a brief presentation and answer questions pertaining to their responsibilities in the development process. The presentation and demonstration should not last for more than 15 minutes. Expect another half hour of questions and discussion directed by your TA.
• In large software projects, the requirements often change during development. After the preliminary release, we will give you an amendment: a request for an additional feature. How easy it is to accommodate it will depend on well you have designed your client to anticipate reasonable increments of functionality. In judging your final release, the new feature will be considered one of the required features.
• All deliverables should be handed in electronically. Late handins will be heavily penalized; for the final release, because of end-of-term constraints, late handins will not be accepted.

Turn in

You should tag the code in your cvs repository for the preliminary release so that we can view the source code. You must do this by 5PM on May 1st. Tagging the code will allow you (and us) to go back to the codebase that you submitted for the preliminary release. If you do not do this by the deadline, you will not receive credit for the preliminary release.

Follow these steps to create the tag:

1. Change to the directory of your cvs working directory.
2. Use cvs update or Team » Update to ensure that this directory contains the version of your software which you wish to tag.
3. Create the tag: cvs tag preliminary-release

Later, if you wish to go back to the tagged version, run cvs update -r preliminary-release. This will put that revision in your workspace. You will not be able to commit from that workspace. If you wish to go back to the main trunk, run cvs update -A.

You should email your TA with the following information:

1. The location of your cvsroot.
2. The name of the module to check out.
3. Instructions for running each demo in the required functionality.

Your ta will run "cvs -d <your cvs root> co -r preliminary-release <your module>" and then follow your instructions to test the demo.