← Back to course
Intro to CS 9-10 / Week 08 / Thursday
4/6
Week 08 · Test, Debug, Document

Thursday

Write it down for the next developer
// Test plans, four kinds of errors, and guides that help others fix problems
⏱ about 20 min

Thursday: Write It Down for the Next Developer

The night crew at mission control finds a strange Beacon reading while the team is asleep.

In the morning, Comet finds their note. "We could not tell what the average procedure was supposed to do. We left it alone."

Comet groans. "It was all in my head."

Wren nods slowly. "Then nobody else could fix it. Next time, we leave a trail."

Nova projects Comet's procedure with blank lines between the steps. "Interesting," she says. "There is room here for words."

"Comments," Wren says. "And a troubleshooting guide the night crew can follow without us."

Documentation and comments

Program documentation is a written description of what a code segment, event, procedure or program does, and how it was developed.

Comments are documentation written inside the program for people to read. They do not affect how the program runs.

Programmers should document a program throughout its development, not only at the end.

In Beacon's pseudocode, the crew starts each comment with two slashes. That is the crew's own choice.

// average: returns the mean of a list of readings.
// Assumes the list has at least one reading.
// Fixed in week 8: total now adds each reading.
PROCEDURE average(readings)
{
   total ← 0
   count ← 0
   FOR EACH reading IN readings
   {
      total ← total + reading
      count ← count + 1
   }
   RETURN(total / count)
}
StatementTrue or false?
Comments change what a program does when it runs.?
Comments are written for people to read.?
Documentation should wait until the program is finished.?
Documentation can describe how a procedure was developed, not just what it does.?
WHY THIS EXERCISEGood documentation lets someone else understand, test and fix your code.

Ways to find errors

Effective ways to find and correct errors include test cases, hand tracing, visualizations, debuggers, and adding extra output statements.

This week you used three of them on paper: test cases, hand tracing and an extra DISPLAY line.

WHICH METHOD IS IT?
  • Read the question.
  • Tap your answer.
You follow the code line by line on paper, writing each variable's value.
You add DISPLAY(total) inside a loop to watch total change.
You run the program on 0, 100 and 101 and compare with expected outcomes.

A troubleshooting guide

Troubleshooting also relies on experience: noticing that a problem is like one you have seen before, or reusing a fix that worked.

A guide such as a flow chart passes that experience on, so others can find and fix errors step by step.

Here is the start of Beacon's guide for the night crew.

Beacon shows a number that looks wrong
↓
Is the reading between 0 and 100? If not, check the sensor
↓
Rerun the test set. Which tests fail?
↓
Hand trace one failing test, or add a DISPLAY line
↓
Fix one line, then rerun every test
↓
Write what you found in the troubleshooting log
PUT THE TROUBLESHOOTING GUIDE IN ORDER
  • ?Hand trace a failing test to find the bad line.
  • ?Rerun the test set to see which tests fail.
  • ?Check that the reading is between 0 and 100.
  • ?Record what you found in the log.
  • ?Fix one line, then rerun every test.
WHY THIS EXERCISEA guide in a clear order lets someone without your experience fix the problem.
Try it
Find the instructions for something at home, such as a board game, a recipe card or a device guide.
Do they include a troubleshooting section? Write one step you would add for a new user.
What is the name for documentation written inside a program for people to read? Type one word.
WHY THIS EXERCISEComments keep the explanation right next to the code it explains.
On paper, add two more boxes to Beacon's troubleshooting flow chart for a problem you predict the night crew might meet.

Great documenting. Tomorrow you will test Beacon with the people who use it.

← Wednesday