Hints on Writing Reports

In your study of Computer Science you will be given numerous assignments which will require you to write computer programs and submit reports of what you have done. This section describes in general terms what a typical report can contain and how they are evaluated. You will probably find that tdocumentationv (the writing of reports describing programs) account for 50 percent or more of the grade for an assignment.

There is no algorithm for writing a good report; good writing is an art form. Basically what you are attempting to do is to clearly and concisely describe what it is that you have done and how others may make use of your work. When writing, you need to be aware of what assumptions and skills your readers have. To that end it is useful to think of your documentation as describing a TTC Bus to three categories of readers:


General Format and Content for all Reports

Each of the reports is to be prepared in a professional manner. To create the report, use any HTML editor to create the documentation file, and then print the file. You will learn how to use HTML in the course. Lab 3 guides you through learning HTML and provides a template for a report in the style outlined in this appendix. If you are using your own computer, you may use your own word processor software. We now describe the major sections of the report.

Title Section: Each report is REQUIRED to have a title section containing the following:

COSC 1020 - Assignment (number) - Date: dd/mm/yyyy

By: Last name, First name

ID: 123456789, Login: cs912345

Section: Registered in section letter, attending section letter

Table of Contents: The second section of a report should be a table of contents listing the different sections of the report in the order in which they appear. No page numbers are needed but you must number the sections and separate them by a ruler line (using the HR tag):

Table of Content

    1. The Problem
    2. User's Guide
    3. Programmer's Guide
    4. Algorithm Design & Implementation
    5. Error Checking
    6. Testing
    7. Code Listing

If the assignment has multiple parts, you need these seven sections for each, but your report should have one table of content only. In that case, use Roman letters for parts and number the sections as I.1, I.2` II.1 and so on.

NOTE: The most efficient way to write programs is to produce the outline of the report describing the program first. Before you can program you require a plan of what you want the program to do and how you expect to accomplish your goal. The report in its early stages is the specification of the program you want to write. It is a guide to you during the programming stage. Therefore, document first!

The Report Body contains the seven sections mentioned above plus any additional section that you think is warranted. In writing these sections, keep in mind that the marker has a limited time to look at your report, so be concise yet as complete as possible. The use of diagrams (to illustrate algorithms and structures) often enhances documentation without taking up too much space.

1. The problem: A description of the problem being solved. What (not how) your program or solution can do and what limitations it has.

2. User's Guide: A description of how to use the program. Assuming the user knows how to access and use the computer on which the program is run, describe in detail everything that a user needs to know about your particular program to be able to use it correctly and recover from errors. Typical contents for this section include:

3. Programmer's Guide: A description of how a programmer can use your classes as part of his/her programs. If you have included documentation comments (javadoc style) in your program, then there is no need to duplicate the information here. In that case, simply refer to your code listing and add any further programmer-related documentation here.

4. Algorithm Design & Implementation describes the algorithm used to solve the problem, proof of its correctness (applicable for non-trivial problems only), its complexity (if applicable) and how it was implemented (translated into code). Implementation is assessed not only in terms of correctness but also in terms of style. Programming style has to do with readability and reusability. Here are a few guidelines:

5. Error Checking: Description of what errors your program checks for and how it does this. Also describe here any errors that your program does not check for.

6. Testing: A series of test runs for the program. Users and programmers want to have some confidence that your program is correct and also be able to verify that they have followed your directions correctly by duplicating the test runs. To have confidence in a program it is important to show that you have tested your program for offbeat input values as well as standard run of the mill values. Show what your program does for erroneous input. It is also important to test your program for boundary values of input variables to make sure you are distinguishing cases carefully. Examples of boundary values are: no input, one value if a list is expected; and so on. Use the method outlined in Lab 1 for generating execution logs and insert the script file here.

7. Code Listing. Simply insert your program here.