Suggestions for clear lab reports in computer science courses

A very short sample lab report is available entitled Counting Real Roots of Quadratics

General advice

In general, your lab should be presented in a self-contained manner, and summarize what you accomplished, what conclusions you drew and why. The lab assignments have questions which were chronologically ordered to indicate how we recommend you accomplish the tasks for the lab, but this is not the clearest way to present most reports. Instead, you should break up your report into logical pieces, and tie the pieces together with an introduction, conclusion, and other helpful comments.

Assume the audience includes people who have taken a similar course but somewhere else. So they haven't read the book, nor have they read the lab description. Your introduction should explain why they should read your report and give a roadmap explaining its structure. Your conclusion should summarize what the reader should have learned. Do not include in your report what you learned from doing it.

It is your responsibility to test your code thoroughly as you write each procedure and to convince the reader that you know all your code works. 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.

Lab report DOs and DON'Ts

Do use complete sentences, with proper grammar and spelling.
Don't blindly write up your lab in the same order and format as the lab assignment.
Do structure your lab 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 lab questions. Don't write ``Prelab'' or ``Question 1'' nor ``Exercise 3.1''.
Don't use phrase 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 SchematiX 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.

More DO's

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.