CSE 15L, Spring 2010

Scientific Debugging

Individual Lab Reports

Lab reports are written individually after each lab is finished, unlike lab notes, which are made collaboratively with a partner during the lab.

When submitting, follow the instructions below.

How to Write Lab Reports

Your lab report should be well organized and contain a careful and precise explanation of your process solving the most interesting failure in that lab. The most interesting failure is the one that took you the most experiments to understand, the one for which you invalidated the most hypotheses, the one that really stumped you and took the longest. This is the one that makes the best story, with the most dramatic tension, complications and obstacles for you and your partner, our protagonists, to overcome!

All that said, you and your partner don't have to agree which failure was the most interesting. You don't even need to talk about it. You can write about different failures; your reports are independent.

Unlike your quick, rough lab notes, the report itself should be polished. As you write, keep the following points in mind:

Use terms precisely. Terms from scientific debugging like hypothesis, prediction, experiment, results, and conclusion should appear in each report. Show you clearly understand them; hypotheses especially. Distinguish between failures and defects. Use appropriate technical terms to describe programming concepts.
Tell the whole story. For tricky bugs a first hypothesis is often wrong; don't leave it out! Include it, and explain how your results invalidated it. Mention all the experiments you conducted, and why you chose them. Don't leave out experiments that were inconclusive! Also remember to describe the intended behavior at the beginning.
Tell the story in order. In general you'll start by describing the failure you observed, then explain how you discovered the defect and eventually removed it. If you saw a defect before a failure, say so, but explain how you actually produced the failure before you fixed it.
Summarize raw data. Don't include blocks of code and raw input and output; just explain what you saw that was important. If you spotted a pattern, describe it and illustrate it with an example integrated into your writing.
Include key details. If you tried different input, how was it different? If you changed code, what exactly did you change? If the program behavior or output was wrong, what was wrong with it?
Convince the reader. Clearly explain your process and reasoning: Why did you do what you did? How did you know what you knew? And support your assertions with evidence: if you claim a bug is fixed, or that the program works correctly, mention the experiments and results that led to this conclusion.
Write well. Take the time to distill and clarify your thoughts. Use correct grammar and spelling, and complete sentences. Use the past tense indicative mood ("we tried") rather than, for example, the present tense imperative mood ("try"). Give each paragraph just one main idea.
(Optionally) Reflect on what you learned. If in retrospect you realize you should have done something differently, explain the lesson imparted by your experience.

The format is flexible. You can write in ordinary prose or use an outline form based on the steps of scientific debugging method, but either way, use complete sentences. If you write in prose, break between paragraphs. In plain text, blank lines make good visual breaks.

If you use an outline form, explain how you got from one step to the next. Don't just state the failure and then state the hypothesis, for example; hypotheses don't just come out of nowhere. Tell us how you developed them.

Submitting Reports

The deadline for reports is midnight at the end of the day they're due. Late reports will be subject to increasing penalties. Here's how to submit reports:

Put the report in plain text in the body of an e-mail message. Please do not attach documents.
Include your name at the top of the message.
Use the correct message subject. Suppose you've just written a report for Lab 1 and your UCSD account name is jdoe. (Your UCSD account name is the part before @ucsd.edu in your e-mail address.) The subject of your message must be report 1 jdoe.
Send the e-mail to cse15L at ucsd.edu.