Best Practices for Debugging

Nothing makes my coworkers and I groan as much as when our product manager announces that we need to do full regression testing before a new release.

It’s tedious and time-consuming. And it turns up lots of bugs, which is of course the idea.  

So now that you’ve identified the bugs, what’s the best course for communicating, finding, and fixing them?

Communicating

The first step to successful debugging is communicating the problem to the dev team. While that sounds obvious, how it’s handled can waste or save a lot of time.

If the bug is being reported by a customer, then start by getting all of the information you can about the environment the bug is occurring in. You’ll want to know:

• What does the error message, if there is one, say?
• Hosting – Did the error occur in Cloud, Server, Data Center, all of the above?
• User role – What kind of users are experiencing the bug? What permissions do they have?
• Which browser(s) does the error occur in?
• What version of the software is the user running?
• What are the steps to reproduce the error?
• Can the customer send screenshots, a screen recording, or error logs?

As much as possible, try to collect all of this information in one place. You don’t want your dev team to have to comb through a long comment chain to find the information they need.  You can save time by adding a form that collects the information above on the issue, adding custom fields (such as “Steps to reproduce”) to a transition screen, or structuring your Description field so it shows all fo the pertinent information at a glance.

If you’re doing internal testing, the you might want to consider using a bug reporting app such as the  Disbug Chrome extension, or these options from the Atlassian Marketplace.

Find It

Sometimes things are simple. Your IDE tells you where (and sometimes even what) the problem is. In other cases, the greatest challenge in debugging isn’t fixing the problem, it’s finding the problem. Here are few strategies that can help you pin down where, in all those lines of code, the problem lies:

• Start with the error message  
  This is obvious, but easily overlooked. The error message, assuming there is one, is your starting point, and it can tell you what kind of problem you’re looking for (undefined variable, type, syntax, etc.).
• Compare what’s working to what’s not
  This could mean comparing versions, or comparing across different environments which may have multiple factors. If you’re working in the Atlassian ecosystem and have a customer report a bug for a version that’s working for all your other customers, find out what other add-ons the customer uses. Sometimes app are incompatible, or both function, but not in the order they need to.
• Examining the logic
  What is the expected behavior? What is the actual behavior? Stepping back and thinking through what the code is trying to do can also help you identify key places where something could easily go wrong. Then you can set your breakpoints accordingly and step through the code to find the problem.
• Step through the code
  If comparisons and logic don’t get you anywhere, then you need walk through the code, step by step, to see where it takes you. It might not be following the path you expect. Set break points at regular intervals and see what happens. Regardless of whether the code stops running, or keeps going, you’ll learn some important information. Once you’ve identified the general area where the code runs into trouble, you can further isolate the problem by commenting out a section and then un-commenting line by line to isolate the problem.
• Print the variables
  If you’ve found the place, but are still baffled by the problem (i.e. you’ve ruled out things like misspellings, mistaken capitalization, and wrong variable types), do a print line of your variables.  It’s possible that they’re not holding the values you think they are.

Fix It

You found the problem! You fixed it. Or did you? Chances are you found more than one thing. So to ensure that you’re implementing a viable solution, retest each change that you make (after seeing that the change worked, remove the change to verify that the system breaks again). This will help you stay clear on what you’ve done in the code and will ensure that your fix(es) can stand on their own.

When You’re Stuck

Many programmers say that the best thing to do when you’re really stuck is to stop and think. Think through the logic of what the code is trying to do. Explain it to your cat or a rubber duck. Going through the logic step by step can help you identify likely trouble spots.

Another good strategy is to take a break. Take a walk. Take a nap. Take a shower. Come back with a clear head. Sometimes, while your conscious brain is taking a break, your subconscious brain figures out what the solution is!

The other thing to do when you’re stuck is ask for help. Being either too familiar or too unfamiliar with the code can work against you. If you’ve been staring at it for hours, there may be something you can’t see that will be obvious to one of your co-workers.

Document It

Hooray! You’ve found the problem. You’ve fixed the problem. Time for a beer.

Not so fast. It’s not done until it’s documented. This is especially important in complex systems and even more crucial when you’re working remotely. Your other team members need to know what you did and why.  Document your changes:

• In the description field, or in a custom field created created for the purpose, on the Jira issues. This will make it fast and easy for the QA team know what you changed, so they know what to review and test.
• In your internal documentation so all members of your team, including the ones you haven’t hired yet, know what’s going on.
• If the change impacts functionality, you need to make sure that the technical writer who’s responsible for your public documentation knows about it. You may want to create an automation rule that creates a subtask, or send a notification, when a Bug type issue is transitioned.

Mistakes are part of life, or at least part of software development. Good practices can make them faster and easier to deal with so you can get back to creating (intentional!) features.