Between The Code

thoughts on coding and everything in between

Practical Troubleshooting Advice

It may be more glamorous to develop new code, but troubleshooting is something we all will have to do at some point. While it may not be as much “fun” at times, learning to troubleshoot well can serve good purposes as well such as making us better at our craft (if we are paying attention). Here are some points of advice that I have found helpful in getting to the root of a problem in a timely manner. This list is certainly not complete, and I welcome any additional points others of you have found helpful.

 1.      Know the starting point. This is more than just having the error or bug report. You need to pay attention to the details about the problem. If you are getting an error message while debugging, don’t just skim it, read it carefully. The same goes for any error – pay attention to the information given. If the problem being reported is from a user, you will most likely have to do some detective work to figure out you true starting point. Know your users. Who is reporting the error? What were they doing when they got the error? Do as much information gathering as you can before you start troubleshooting to find and fix the problem which leads me to tip 2.

 2.      Reproduce the error. If you can reproduce the error following all the same steps the user followed you will have a lot more information to work with and you will know where to start debugging. Keep in mind in reproducing the error what the environment of the user was at the time they got the error – the steps they took,  their setup at the time of the error, and what they expect to see are important.

 3.      Take the reported problem seriously, especially if it has happened more than once. Don’t fall into the trap of “that always happens” or “that person is always saying something is wrong”. When you start thinking that way, you may possibly miss a real issue and then have to stay late to fix it! And don’t let that kind of thinking blind you to the real solution.

 4.      Don’t make assumptions. If you think something is happening but don’t have the proof for it, you are much more likely to miss the real solution to the problem – then you will have wasted time researching the wrong thing and of course the problem with remain unsolved.

 5.      If you are debugging code, be purposeful about your breakpoints. Breakpoints should be placed in logical locations and if you have done the work of tips 1-4 you should have a better idea of where it makes sense to place breakpoints. If you find yourself stepping through multiple methods and more than one class, think about whether or not you really understand the problem and if you have enough information. Revisit tip 3 – have you reproduced the error first?

 6.      Be familiar with your debugging tools. Some languages of course may not have rich debugging tools so you might have to get “creative” with things like inserting output strings or select statements to let you know what is going on throughout the process. However, don’t miss out on free tools that are out there! If you find yourself thinking there should be a tool to help you debug, go search for it. It might even be that your development environment already includes these tools but they aren’t immediately apparent so again, ask for a little help from the community.

 7.      Ask for help. If you have people on your team that are more familiar with the application, don’t spin your wheels for more than 30 minutes before asking them. They just might have some great knowledge you need. There are also great tools on the internet like Google, Stack Exchange (previously Stack Overflow),  MSDN, user groups & forums, etc. You have to have a good grasp on your problem of course so before you jump into using the internet to solve all your problems, make sure you have taken a look at the tips prior to this.

 8.      If you think you have found the answer – re-verify. Take a second look at why you think this is the solution. If it sounds like what you think is going on is an impossibility, it just might be! Are there assumptions you have made? If so, go back and prove them. Think about how to explain the solution – can you put it in simple enough terms to give an “elevator pitch”? Can you explain it to your boss and answer all the questions he will have? Also use your development environment to try to apply your solution and see if the problem goes away. This of course should only be attempted if you have been able to reproduce the problem first!

 9.      Do better! Once you have found the source of the problem, have verified it and rid yourself of assumptions, look for how the code can be improved, not just fixed. If you have time, re-factor mercilessly! If you don’t have the time, at least take the opportunity to make small improvements rather than quick patch jobs. You don’t want to have to come back to this next month and fix what you fixed!

10.  Document. I can hear the moans and groans from the other side of this blog posting, but before you fall on the floor in a pretend coma the kind of documentation I am talking about is just to detail in a work item or knowledge base somewhere what the problem was, how you found the source of the problem and what you did (or are doing) to fix it. This documentation should be specific, have enough detail to provide good context, be short enough to fit into about two paragraphs (or less. If you happen to be the one to have to go back to this later, you will be glad you took 5 minutes to document your troubleshooting! Just think how quickly all this troubleshooting would have taken if you would have had this documentation from the start!


4 responses to “Practical Troubleshooting Advice

  1. candeo7 March 29, 2011 at 9:09 pm

    Love it–esp. the part about meaningful breakpoints!

  2. Ahmad Mageed March 30, 2011 at 3:56 pm

    Nice post! As I was reading I couldn’t help but think of related points. I’ve found two strategies to be extremely useful when I’ve hit a wall during debugging. The first strategy is to simply get up and walk away from your desk. Take a walk around the building, get some coffee, or similar. Disengage your mind! That helps refresh your thinking and sometimes the solution comes to you when you’ve stepped away from the keyboard. The second strategy is rubber duck debugging, as mentioned in this blog post: The idea is to talk through the issue while conversing with your rubber duck, or whatever you keep on your desk, or even a coworker. As the conversation unfolds, the solution may just pop up. Plus, talking to a rubber duck looks less crazy than talking to yourself! 🙂

    Tip #2 & #6: IntelliTrace is an awesome tool to benefit from for any team using Visual Studio 2010 Ultimate.

    Tip #5: completely agree about the breakpoints. If your fix didn’t work or you have to revisit the same area and still aren’t aware of the program flow then you haven’t properly understood the code’s purpose.

    Tip #7: StackOverflow is still the go to site for *development* help. Just a minor clarification that the name change was more for the company that owns it; i.e., StackExchange emphasizing the variety of other sites in its network of sites.

    Tip #9: The task might not be fun, but you get out of it what you put in. There are times where a dev is tasked with fixing an issue they find boring, but a smart dev would recognize an opportunity (time allowing) to jump in and make positive changes to the code. Changes should be within reason, of course, so as not to break existing functionality. If unit tests are in place they help verify that everything is fine.

    Tip #10: *groan* … j/k! To add to this point, commenting a complicated bit of code is also a great documentation opportunity.

    Thanks for the thought-provoking post!

    • slhpowell April 1, 2011 at 8:58 pm

      Great additional points. I agree, sometimes the best way to get out of a troubleshooting “rut” is to take a walk or have a talk (how’s that for cheesy? ;)) Thanks for the additional clarifications as well.

  3. Jeff April 18, 2011 at 5:27 pm

    Great points. I have to say, I personally don’t want anybody building any new code on my team who hasn’t been through the fire of troubleshooting critical issues with a time constraint and an impatient boss breathing down his neck. It’s this kind of refinement in the thought process that will lead to sounder designs down the road.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: