Suggestions for clear reports in computer science courses
A very short sample project report is available entitled
Counting Real Roots of Quadratics
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
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
Using code in your reports
You will write, test and debug code for all of the projects, and you will
often need to put this code in your paper. You want to do this in
such a way that your reader can easily understand what the code does and
how it works. You also need to convince the reader that the code
does work, usually by using a combination of giving a proof and
presenting (i.e., describing and giving examples of) your testing.
- 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
fixed-width character font like courier or typewriter
font for your code and tables so that the indentation and columns line
- 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
- 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
- Do summarize the results of procedure calls in a readable
form. When appropriate, this could include
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
- 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.
- Don't mix verb tenses. Usually, I would recommend sticking to
- If small changes are made to large blocks of code, use a different
font (italic or bold) to highlight your