Debugging Techniques and Tools

Why First Attempts Fail

A program that fails on its first run is not evidence that programming has gone wrong. First programs rarely work perfectly on the first attempt, and this is normal and expected, including in professional programming. Testing and debugging are the phases in which you verify that a program works and fix errors that prevent it from working correctly.

The Two-Layer Problem

A backup program can involve two layers: the Python program and the system command that Python calls. A backup program typically calls a system command such as the zip command to compress and archive files. If the backup operation fails, the first question is not simply “Which line of Python is wrong?” The more useful question is “Which layer contains the problem?”

The two layers require different investigations. If the command fails when tested manually, the backup operation has a problem at the command layer. If the command works manually but the backup program fails, the error is in the Python code or in how that code calls the command. This isolation step prevents you from changing Python code when the underlying command is the real problem.

A Systematic Backup Investigation

When a backup program fails, investigate in a fixed order rather than randomly trying changes. First test the relevant system command manually. Then use the result to choose the next layer to inspect. This procedure isolates the problem before you attempt a fix.

1. Recognize that the backup operation did not behave as expected.
2. Test the system command manually instead of immediately changing the Python program.
3. If the command fails manually, investigate the command layer.
4. If the command works manually but the program fails, investigate the Python code and how it calls the command.
5. After making a correction, test the backup again and use the new result to guide the next investigation.

Design, Syntax, and Implementation

Not every failure should be fixed in the same place. When a program does not behave as expected, first decide whether the problem is in the design or in the implementation. A design flaw means the plan itself needs reconsideration. An implementation mistake means the plan may be suitable, but the code does not carry it out correctly.

Syntax and behavior belong to the code-level investigation. A syntax problem means the Python code is not written in a valid form. A behavior problem means the program runs but does not perform the intended operation. In either case, debug the implementation. By contrast, if the intended backup process itself is unsuitable or incomplete, return to the design phase instead of repeatedly changing code that is faithfully following a flawed plan.

The Retest Cycle

Testing and debugging are not one-time events. They form a cycle: run a test, observe the result, identify the likely source of the problem, change the design or implementation, and test again. A correction is not complete merely because the code has been edited. The program must be tested again to determine whether the intended behavior has been achieved or whether another problem remains.

Worked Backup Investigation

Mistakes That Waste Time

• Assuming a first run should work perfectly

  First programs rarely work perfectly on the first attempt, and testing and debugging are expected parts of programming.

  Fix: Use the failure as evidence and begin a systematic investigation.

• Changing Python code before testing the system command

  The backup program has a Python layer and a system-command layer. Changing the wrong layer can hide the actual source of the problem.

  Fix: Test the command manually first and use its result to choose the next layer.

• Treating every failure as an implementation mistake

  Some problems are design flaws and require a return to the design phase.

  Fix: Decide whether the plan is wrong or whether the code fails to implement a suitable plan.

• Stopping after making one edit

  Testing and debugging repeat as a cycle, and the new version must be tested to verify its behavior.

  Fix: Retest after each appropriate correction and use the result to guide the next step.

Practice the Decision Path

Key Takeaways

1. First programs rarely work perfectly on the first attempt; testing and debugging are normal parts of programming.
2. A backup program can fail in the system command layer or in the Python layer that calls the command.
3. Testing the command manually isolates the command layer from the Python layer.
4. A design flaw requires returning to the design phase, while an implementation mistake requires debugging the code.
5. Testing and debugging form a repeating cycle of testing, diagnosis, correction, and retesting.