Python Debugging Techniques for Students | Beginner's Guide

def get_average(grades):
    total = sum(grades)
    average = total / len(grades)
    return average

my_grades = [85, 92, 78]
avg = get_average(my_grades)
print("The average is: " + avg)

Traceback (most recent call last):
  File "/home/user/main.py", line 7, in <module>
    print("The average is: " + avg)
TypeError: can only concatenate str (not "float") to str

Step 2: The Art of the Print Statement

The most fundamental python debugging tool is the print() function. When in doubt, print it out.

Explanation: Sprinkle print() statements throughout your code to check the values of variables at different stages. This confirms whether your code is doing what you think it’s doing.

Why it matters: Many bugs happen because a variable doesn’t hold the value you expect. Printing reveals the “state” of your program.

Concrete Example:

Consider a function designed to find the largest number in a list:

def find_max(numbers):
    max_num = 0
    for num in numbers:
        if num > max_num:
            max_num = num
    return max_num

test_scores = [-5, -10, -3]
print(find_max(test_scores)) # Output: 0 ... That's wrong!

def find_max(numbers):
    max_num = 0
    for num in numbers:
        print(f"Comparing: {num} with current max: {max_num}")
        if num > max_num:
            max_num = num
            print(f"  New max found: {max_num}")
    return max_num

test_scores = [-5, -10, -3]
print(find_max(test_scores))

Output:

Comparing: -5 with current max: 0
Comparing: -10 with current max: 0
Comparing: -3 with current max: 0
0

The print statements reveal the bug immediately. We initialized max_num to 0, but all our numbers are negative. Since -5 is not greater than 0, the max_num never updates. The fix is to initialize max_num to the first item in the list.

Step 3: Use “Commenting Out” to Isolate the Problem

If your entire script is broken, you need to narrow down the search.

Explanation: Systematically comment out sections of your code to isolate where the error or unexpected behavior is originating. Start by commenting out half of your code. If the error goes away, the bug is in the commented-out half. Keep narrowing it down.

Why it matters: This process of elimination is much faster than staring at hundreds of lines of code.

Concrete Example:

Imagine a long script that reads a file, processes data, and then saves a result. If you get an error, you can start by commenting out the file-saving part. If the error persists, comment out the data processing part, leaving only the file reading. If the error disappears, you know the bug is in the data processing block.

Step 4: Leverage Logging for Complex Programs

For larger assignments, print() statements can get messy. The logging module is a more professional alternative.

Explanation: The logging module allows you to output messages with different severity levels (DEBUG, INFO, WARNING, ERROR). You can easily turn logging on or off without deleting all your print() statements.

Why it matters: It helps you keep track of your program’s flow in a structured way, especially when dealing with loops and function calls.

Concrete Example:

import logging

# Basic setup to show info messages
logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')

def process_data(data):
    logging.info(f"Starting to process data: {data}")
    total = 0
    for i, item in enumerate(data):
        logging.debug(f"Processing item {i}: {item}") # This won't show yet
        total += item
    logging.info(f"Finished processing. Total: {total}")
    return total

my_list = [1, 2, 3, 4, 5]
result = process_data(my_list)

By setting the level to INFO, only the INFO messages appear. If you need more detail, you can change the level to DEBUG to see the more granular messages without adding or removing any code.

Step 5: Master the Python Debugger (pdb)

When print() isn’t enough, it’s time to bring in the big guns: the built-in Python Debugger, pdb.

Explanation: pdb allows you to pause your program at a specific line and interactively inspect its state. You can step through code line by line, print variable values, and even change them on the fly.

Why it matters: It gives you a live, interactive view of your program as it runs, which is incredibly powerful for understanding complex logic.

Concrete Example:

Add this line to your code where you want to start debugging:

import pdb; pdb.set_trace()

def calculate_average(grades):
    total = sum(grades)
    import pdb; pdb.set_trace()  # Execution will pause here
    average = total / len(grades)
    return average

scores = [90, 85, 92, 88, 100]
result = calculate_average(scores)
print(result)

When you run this, the program will stop at pdb.set_trace() and give you a (Pdb) prompt. From here, you can use commands:

• p total: Prints the value of total.
• p len(grades): Prints the length of the grades list.
• n: (next) Executes the next line (average = …).
• p average: Prints the newly calculated average.
• c: (continue) Runs the rest of the program normally.
  Ready to go deeper? Join our expert sessions to learn more advanced debugging strategies.

Step 6: Rubber Duck Debugging

This might sound silly, but it’s one of the most effective techniques.

Explanation: Get a physical object—a rubber duck, a stress ball, anything—and explain your code to it, line by line, out loud. State what each line is supposed to do.

Why it matters: The act of speaking forces you to slow down and think deliberately. Often, the moment you articulate the problem, you realize the flaw in your logic. “Mr. Duck, I set this variable to zero, but the list only has negative numbers in it… wait a minute…”

Step 7: Check for Off-by-One Errors

A massive source of bugs in loops and list indexing.

Explanation: Remember that Python uses zero-based indexing. The first element of a list my_list is at index 0, and the last element is at index len(my_list)-1.

Why it matters: Looping from 1 to len(my_list) will skip the first element and cause an IndexError at the end.

Concrete Example:

# Buggy code that skips the first element
my_list = [10, 20, 30, 40]
for i in range(1, len(my_list)): # Starts at index 1, so prints 20, 30, 40
    print(my_list[i])

# Correct code
for i in range(len(my_list)): # Starts at index 0
    print(my_list[i])

4. Common Python Debugging Mistakes Students Make

Knowing what not to do is just as important as knowing the right techniques.

1. Changing Code Randomly (The “Shotgun” Approach)

• What it looks like: You get an error, so you start adding and removing lines, changing syntax, and renaming variables without a clear reason, hoping something will work.
• Why students make it: Panic and lack of a systematic process.
• How to avoid it: Stop. Take a deep breath. Read the error message. Form a hypothesis about what’s wrong, then make one change to test that hypothesis.

2. Ignoring the Full Traceback

• What it looks like: You only read the last line of the error (“TypeError”) and start debugging the function where it occurred, missing the fact that the function was called with bad data from elsewhere.
• Why students make it: The traceback looks complicated and scary.
• How to avoid it: Train yourself to read the traceback from top to bottom. It tells the whole story of how your program arrived at the error.

3. Forgetting to Convert Data Types

• What it looks like: Getting errors when trying to combine numbers and strings, like input() which always returns a string.
• Why students make it: It’s easy to forget that data from users or files isn’t always the type you need.
• How to avoid it: Use print(type(my_variable)) to check a variable’s type. Use int(), float(), or str() to explicitly convert.

4. Misunderstanding Variable Scope

• What it looks like: A NameError saying a variable isn’t defined, even though you’re sure you created it.
• Why students make it: Not understanding that variables defined inside a function (local scope) are not accessible outside of it.
• How to avoid it: Learn the difference between local and global scope. If a function needs to produce a value, use return.

5. Assuming Code Works Without Testing

• What it looks like: Writing an entire program, running it once at the end, and being overwhelmed by a flood of errors.
• Why students make it: It feels more efficient to write everything first and test later.
• How to avoid it: Test as you go. Write a small function, test it immediately. Add a loop, test it. This is called incremental development and it’s a hallmark of good python error analysis.

5. Frequently Asked Questions

Q1: I get a SyntaxError: invalid syntax but my code looks right. What do I do?

A: Look at the line the error points to, and often the line right before it. Common causes are missing parentheses from a previous print statement, forgetting a colon : at the end of an if or for statement, or unclosed string quotes.

Q2: What’s the difference between a NameError and a TypeError?

A: A NameError means you’re trying to use a variable or function name that Python doesn’t recognize (e.g., print(age) when age was never defined). A TypeError means you’re performing an operation on a data type that doesn’t support it (e.g., trying to add a string and an integer with +).

Q3: How do I debug an IndexError: list index out of range?

A: This means you’re trying to access an element at a position that doesn’t exist. For example, trying to get the 5th element from a list that only has 3 items. Print the len(your_list) and the index you’re trying to access. Double-check your loop conditions to ensure you’re not going past the end.

Q4: My code runs but gives the wrong output. How do I fix it without an error message?

A: This is a logic error, the hardest type to fix. You need to use python debugging tools like print() statements or pdb to trace the execution. Print the value of key variables at different points to see where the value diverges from your expectation.

Q5: What are the best Python debugging tools for beginners?

A: Start with print() and learning to read tracebacks. Once you’re comfortable, move on to the built-in pdb debugger. For a more visual experience, use an IDE like VS Code, PyCharm, or Thonny, which have built-in debuggers with clickable interfaces to set breakpoints and inspect variables.

Q6: I’m using input() but my comparisons don’t work. Why?

A: The input() function always returns a string. If you’re comparing it to a number (e.g., user_input == 5), it will always be False because a string “5” is not the same as an integer 5. Convert the input using int(user_input) for numerical comparisons.

Q7: What is a breakpoint?

A: A breakpoint is a deliberate pause point you set in your code. When you run your program in a debugger, it will stop at that line, allowing you to inspect the state of your program before it executes that line. You can set them with pdb.set_trace() or by clicking in the margin of your IDE.

Q8: How do I debug code that uses API calls or reads files?

A: First, isolate the external part. Print the data you get back from the API or the file immediately after you receive it. This confirms you’re working with the data you think you are. Often, the issue is that the data format is different from what you expected.

Conclusion

Debugging is a skill, and like any skill, it improves with practice and the right approach. The next time you’re faced with a wall of red text, don’t panic. Take a deep breath, read the error message, and start your systematic investigation. 

Use print() statements to illuminate the dark corners of your code, or step through it line-by-line with a debugger. Remember, every error you solve is a step toward becoming a more confident and capable programmer.

Don’t let a tricky bug ruin your night. Whether you need a quick code review or deep, one-on-one help understanding a complex concept, our team is here to support you.

• Submit your assignment for a professional code review.
• Book a tutoring session for personalized, step-by-step guidance.
   

Read more helpful articles on our blog.