Details of Program Documentation

General Comments

Project Proposal

What will the program accomplish? How will the target users benefit?
Is there a significant improvement over other methods such as paper files, a calculator, another software package?
Basic functional specifications
This is the most important part of the proposal.
What will the program do? What are the main inputs, calculations and outputs? Be specific.
Target users
Who will use the program? What are their characteristics?
You might not need to go into much detail for these projects, especially if your program is for a general audience.
Content sources
What books and electronic sources did you consult?
Be specific enough that someone else would be able to find it. Include page numbers and URLs.
If you searched and, don't just mention those sites; mention specific sites where you found useful information about your topic.
What existing software is available to perform similar functions?
Find out if spreadsheet or database programs offer similar functions and features, and their strengths and limitations.
List advantages and disadvantages of writing a custom program instead of an office application.
If you will be sharing ideas with others, mention their name(s), but remember that you must do your own work to receive marks.
Method to choose topic
Mention your interests and motivations.
Mention sources of topics you consulted including the course web site and instructor but also books and web sites that have programming topics.
What features will the program not try to implement?
Important: You must submit a program that compiles without any errors.
It is far better to produce a simple program that works than a complicated one that doesn't.
Start simple and get it working. Add on more if time permits.

Design Specification

List the tasks you will perform and the dates during which you will perform them.
For a small project like this you do not need too much detail.
List the software tools you will use for application development, debugging, word processing, image editing, etc.
Functional specifications
What will the program do?
How will the user interface look? Graphics-based or text-based? Interactive, batch or both?
Will the user be presented with a menu of choices or a series of questions?
Will the user type input or send input from a text file? Will the output be sent to the screen or a text file?
What are the range and types of inputs? What will the user see for unacceptable inputs?
Technical specifications
How will the program be designed internally?
What classes of objects will be used? For each object, list and briefly explain its attributes and methods.
It may be useful to start by creating the skeleton of code with class and method declarations and comments but without any method implementation.
What algorithms will the key methods use? Explain algorithms using English or pseudocode.
What mathematical formulas are used in calculations? Explain each variable.
For these projects you can submit hand-drawn diagrams on paper since diagramming using a computer can be difficult and time-consuming.
Show the relationship between your objects (e.g. is-a, has-a) and the flow of messages and data between the objects.

Technical Documentation

Code documentation and format
Every class and every method in your code should have a Javadoc comment of at least one line.
Important sections within methods (e.g. complex algorithms and calculations) should have additional comments.
Code should follow the recommendations for naming and coding style and class structure.
System Requirements
What special system requirements does the program have? (e.g. memory, disk space, etc.)
For small programs, the main requirement is a system that supports Java applications and applets, e.g. has the Java SDK installed.
Pretend you put a .zip file on your web site containing the program. How does the user unzip, install and compile the program?
How does the user run the program?
Is the program graphical or text-based? Is it interactive or batch? Are there any command-line options?
What doesn't work as it should? Are there any bugs that you have not corrected? Describe the problems briefly.
Is the program limited to a certain number of objects or data inputs?
Are there constants with fixed sizes that limit the user's amount of data?
Future Features
What changes could be made and features added to a future version relatively easily?

User Documentation

What is the purpose of the program? Why would someone want to use it?
What can the program do? What are its main features?
User Interface
What choices will the user see? Explain each choice or menu item, perhaps in the form of an outline.
What should the user do or not do? What inputs are valid and invalid?
Answer the user's common questions, e.g. "how can I ...?"
Give examples of input and output, e.g. a test run.