Final Report

This document is under development. Expect some changes.

You are expected to provide an interesting and readable final report on your project. This report may be turned in at any point up to, and including, the date of the final. Unless you have strong arguments to the contrary, your report will be made part of the department's technical report series, so make sure that it presents a good impression of your work, your ability, and the department as a whole.

Your report should include

• user documentation;
• programmer documentation;
• a narrative discussion of your development process

User Documentation

Write a manual that is sufficient for your audience to understand how to use your application. You may want to describe unusual features, unlabeled icons, missing parts, etc. You may put this documentation in any form or forms you deem appropriate, including guided tour or reference manual.

Programmer documentation

The audience for programmer documentation is a maintenance programmer. Obviously, your comments are the front line in documentation for other programmers. Make sure they are clean and up to date.

But you need more than comments. Imagine what a new programmer assigned to work with your code, next year, would need to know to understand your design, your class hierarchy and object inter-relationships, your error handling, your naming conventions, your makefiles, your distribution of code among files, and so forth. I suggest that you start with your design and test documents, fill them out to be more complete and up to date. Diagrams can be useful here; hand drawn diagrams (if legible) are fine.

As these comments suggest, there are three parts to the programmer documentation:

• An overview guide. This will describe the structure of your program, key design decisions, and such.
• Your javadoc documentation for each class. This will describe the purpose and use of each of your classes.
• Inline comments within your code. These will summarize your algorithms (methods) in English and help illuminate the more confusing parts of your code.

I will be depending on this documentation to understand (and grade) your code.

Narrative

For a course like CS223, the process by which you constructed the application is important. I'd like a narrative report on this process that covers not just the time you spent on the project, but also how you spent that time, what difficulties you faced, how your projected schedule differed from your actual schedule, and so on and so forth.

The narrative is the "official history" of the project. It should include important decisions and how they were made; challenges that were or were not overcome during design, implementation, and testing; what the team would do differently if given the benefit of hindsight; and what lessons others should draw from your experiences.

It would be nice, but not essential, if your project narrative were sufficiently detailed that students in the next session of CS223 could use your project for one of the case studies.

Acknowledgements

Much of the text in this document is based on similar handouts by David Kotz and Thomas Cormen. John D. Stone suggested a number of additions and changes.