CSE 15L, Spring 2010

Scientific Debugging

Collaborative Lab Notes

Lab notes are made collaboratively with a partner as you work on each lab, and are used later to write more thorough explanation in your individual lab report.

When submitting, follow the instructions below.

How to Make Lab Notes

Collaborative lab notes for each lab should contain, as much as possible, everything you see and do while working on the lab. Here's how to write good lab notes:

Copy and paste. Copy input, output, code changes, and so on; paste it right into your notes. In the command shell, copy the command together with the resulting output. Generally keep just about everything, but some exceptions are reasonable; if you get a long list of compiler errors at once, it's sensible to copy just the ones you look at before compiling again.

Record as you go. Don't wait until you've fixed a bug to start recording detail. Record what you do and see, as it happens, whether it's what you expect or not, whether or not you understand it yet. It will come in handy later.

Don't skip steps. Record all your experiments and results, especially those that invalidate a hypothesis, don't fix anything, or just don't go as planned. Include experiments and results even if you think they're not interesting. If you see a defect before a failure, remember you still need to show the failure itself in the notes.
Make an objective record. In terms of scientific debugging your notes should document each failure as well as each experiment and its results. The other steps (intended behavior, hypotheses, predictions, and conclusions) are not something you see or do; they're something you think. Explain your thinking in the lab report. (See the next point.)
Don't write too much. If you find yourself composing a sentence, stop. Yes, you need words for observations you can't copy and paste—like "program still running after 10 seconds"—but sentence fragments are OK here. Short notes are OK, but don't try to explain why you did what you did, or how you interpreted what you saw. That takes time, and you need to finish the lab. Writing slows you down. Later, when you have plenty of time, you'll explain everything in full grammatical sentences in your lab report.
(Usually) Include your final code. For short programs this is helpful. Very long programs or those made up of many files should not be included in your notes.

More Tips

These tips aren't just about taking lab notes, but they do affect your notes. Some details below assume Java and a UNIX-like system, but all the advice applies in most any programming environment.

One bug at a time. Finish off each failure before you tackle the next one. Don't tackle two at once.
Save and reuse test input. Keeping input in a file makes it easier to repeat the exact same test, which is a very good idea. Show the contents of those files in your notes. An easy way to do this in the command shell is to run cat test-input.txt (or whatever your file is) and paste, again, the command and the output into your notes.
Make debugging output readable. Instead of System.err.println(var), write System.err.println("var: " + var). Instead of "got here", print "entered methodName()" or "inner loop iteration " + i. Your grader will appreciate it, and you'll thank yourself later.
Save, but disable, debugging code. In the Java class, define a constant like static final boolean DEBUG = true; and then put if (DEBUG) before each debugging statement. Then, instead of deleting or commenting out code, just set DEBUG = false and recompile. Debugging statements you wrote in lab should remain in your final code but be disabled.

Submitting Lab Notes

Collaborative lab notes are due at the end of each lab, before you leave. Here's how to submit notes:

Put the notes in plain text in the body of an e-mail message. Please do not attach documents.
Include your name and your partner's name at the top of the message, and include your partner's e-mail address in the CC header.
Use the correct message subject. Suppose you've just finished Lab 1, your UCSD account name is jdoe, and your partner's is jqpublic. (Your UCSD account name is the part before @ucsd.edu in your e-mail address.) The subject of your message must be notes 1 jdoe jqpublic. Got it? Good!
Send the e-mail to cse15L at ucsd.edu.