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!