Editing, Commenting, and Rerunning Python Code

Use a controlled editing cycle: predict a result, run the program, change one part, and compare the new output with your prediction. Add Python comments and labeled intermediate output to make the purpose of an experiment easier to follow.

Once a program can run, we can learn from changing it. The useful question is not only whether the new program works, but why its result changed.

A short editing cycle makes that question easier to answer: predict the result, run the program, change one part, predict again, and compare the new output with the prediction. Comments and labeled output can record what we intended to test.

Predict, Run, Change, and Compare

Begin with a small program:

Before running it, we can predict:

double: 8

Now suppose we change only value = 4 to value = 7. The calculation remains the same, so the new prediction is:

double: 14

Because only the starting value changed, we can explain the new output without having to separate several possible causes.

This gives us a repeatable cycle:

1. predict what the current code will produce;
2. run it and inspect the actual output;
3. choose one change and predict its effect;
4. run the changed code;
5. compare the new output with the new prediction.

The prediction does not have to be correct. A difference between expected and actual output tells us which assumption to inspect.

Print Intermediate Values

A final answer can tell us that a calculation is wrong without telling us where it became wrong. Printing intermediate values makes more of the calculation visible.

The name double stores the result of value * 2. The two labeled lines let us inspect both the starting value and the calculated value:

value: 7
double: 14

If value is correct but double is not, the calculation that creates double is the useful place to inspect. This is more informative than printing only the final value.

Add a Comment for the Reader

A comment is source text written for a person reading the program. In Python, a comment begins with the # symbol when that symbol appears outside quoted text. Python ignores the # and everything after it on the same line.

The comment records the expectation, but it does not become output:

double: 8

A comment can occupy a line of its own, as above, or follow an instruction:

value = 4  # starting value for this experiment

Both forms use the same rule: outside quoted text, # begins a comment that continues to the end of the line.

A Hash Symbol Inside Text Is Not a Comment

Quotation marks change the meaning of #:

print("# is visible here")

This program prints:

# is visible here

The # is inside quoted text, so it is one of the characters passed to print(). It does not begin a comment.

Compare the two lines:

The first line runs. The second line is entirely a comment, so Python ignores it.

Write Comments That Add Information

A useful comment explains an expectation, a reason, or a choice that the code alone does not make clear.

Useful:

The comment explains why 4 was chosen.

Less useful:

This comment repeats the instruction without adding information. Clear code usually does not need a comment that merely restates it.

Comments can also become inaccurate when the code changes. If value changes from 4 to 400, a comment that still calls it a small hand-checkable value must be updated or removed.

Keep One Cause Changing at a Time

Suppose we change the starting value, the multiplication, and the printed label before running again. If the output is unexpected, we now have several possible causes to inspect.

For a small experiment, it is easier to:

1. keep the current working version;
2. state or comment the expected result;
3. change one relevant part;
4. rerun the program;
5. compare the result;
6. keep the change or restore the earlier version.

This method does not prohibit larger edits. It separates an experiment into steps whose effects we can understand.

Carry the Method Forward

We can now make a program easier to inspect: predict its result, print useful values, record a reason or expectation in a comment, change one relevant part, and rerun it. Expected and actual output then tell us whether the change had the effect we intended.

The chapter conclusion brings together this editing cycle with scripts, interactive sessions, ordinary output, and error messages.