Suggestions for clear reports in computer science courses

General advice

After you have finished solving the problem outlined in the project assignment, you need to write a report that outlines what the problem is, describes your solution, and explains why this is a good solution. This report is similar to papers that you write for other classes in that it should have an introduction, a body and a conclusion.

First, you should select a theme which you view as the most important thing you wish the reader to glean from your report. I.e., try to make some point. Then organize your report to best emphasize that point.

The introduction explains to your readers what the paper is about and why they should read it. It states your theme and also gives a road map explaining the paper's structure. The body presents your solution, along with any code, analysis, or research that you have done. Although most of the assignments present a list of questions that are meant to guide you through the project, you should not use these questions to organize your report. Instead, you should organize it so that you present the material in a logical and coherent manner. Finally, the conclusion should summarize what the reader should have learned. You'll reinforce the theme in the context of the report.

Assume the audience includes people who have taken a similar course somewhere else. This means that they haven't read the book or the project assignment, but that they do know Scheme. If necessary, you may assume the reader has a copy of the book handy so that you can cite it.

Using code in your reports

• Present your code in an understandable way. Remember, the audience you are writing for has read neither the book nor the lab description, so your code should either be self-documenting or have enough documentation so that it's clear what it does.

• Tell me how you tested your code. You don't always need to provide the individual test cases, but you should convince me how you have tested every procedure and why you are confident that each works. If a procedure does not always work, you should report this, too.

• Rather than copy huge pieces of code from the text, summarize the procedures defined in the text. You could, for instance, give a sample procedure call for each procedure, and explain in a sentence what the procedure takes as input and what it returns. This way your report will remain self-contained without blindly copying from the book. Use a fixed-width character font like courier or typewriter font for your code and tables so that the indentation and columns line up properly.

• Often the real point of a lab is to write some major procedure x, but to do so you need to write lots of small procedures, a, b, c, ... to get x to work. If so, you should structure your report so that you get to x as soon as possible. One way to do this is to state the behavior (with, for example, a sample procedure call) of only those procedures which x calls, then describe x, and then include the actual code for the little procedures a, b, c, ... in an appendix.

• If your code has a bug, report the bug and explain your testing and what you know about where the bug is in your program. If you fail to report a bug, the grader will assume you either (a) tested poorly or (b) were dishonest in your report. Either way, your grade should be more severely reduced than if you just report your bug.

Project report DOs and DON'Ts

• Do use complete sentences, with proper grammar and spelling.
• Don't blindly write up your project in the same order and format as the assignment.
• Do structure your paper in a logical way, with each section marked with a helpful title. (``Part 3'' is not helpful. ``Data'' or ``Part 3: Data'' or ``3.1 Data'' is helpful.)
• Don't repeat the programming questions. Don't write ``Question 1'' or ``Exercise 3.1''.
• Do focus on what the reader should learn rather than what you learned or did:
  • Don't use phrases like, ``In this lab we learned about...,'' nor, ``We were asked to write a procedure which, ...''
  • Do use phrases like, ``The following procedure computes ...''
• Don't use the passive voice, ``A procedure was written to ...''
• Don't read the code to me in your comments. (Your documentation should make clear what the code does at a high level, not how it does it at a low level.)
• Don't provide a page of procedure calls with DrScheme return values.
• Do summarize the results of procedure calls in a readable form. When appropriate, this could include
  • Tables whose headings are carefully chosen and whose entries are rounded to an appropriate number of significant digits (2-4 depending on your judgment should be enough for most practical purposes.)
  • Graph(s) whose axes are clearly labeled.
  In either case there should be enough of an explanation so I know what each table entry means and/or what the graph represents. Don't forget to label axes in graphs, and make the units clearly visible in tables and graphs.
• Don't mix verb tenses. Usually, I would recommend sticking to present tense.
• If small changes are made to large blocks of code, use a different font (italic or bold) to highlight your changes.