Tips for identifying and debugging problems

It seems that some/many developers haven’t developed (pun intended) a good set of techniques to identify and resolve problems. And problems always occur, even in simple programs. Recently I’ve been answering a lot of questions on StackOverflow and those questions confirmed my suspicions. Some of the advice here may sound like advice for newbies, but pactice shows they are needed. I’m a Java developer, but the tips below may be considered language-agnostic.

Note that the steps are often regarding Exceptions, but in case there is no exception – just an undesired behaviour, those steps are skipped.

1. Exception stacktraces – these are so often ignored and even considered irrelevant. Stacktraces are the place to start looking for the problem. Not only the exception message, but the line of code at which the exception occurred (in your code, in the library code).
2. The code in question – after seeing what line of code causes the exception, immediately go to that line and see if the problem won’t become obvious. Try understanding the behaviour of the code (even if it is your code!). In case there is no exception, but an undesired behaviour, identify the code that is relevant
3. Google – if it doesn’t become obvious, or the exception/problem occurred somewhere in a framework you are using, rather than in your code, then google the exception message or the problem description. Google it for 15 minutes, trimming various parts of the exception message – most importantly your package and class names. Most of the common exceptions occurring in popular frameworks are explained many times (because people skipped this step)
4. Read the documentation – this is not always applicable, but in cases when the problem/exception regards a concrete component of the framework used, read the documentation about it. As the saying goes – 5 hours debugging save 20 minutes reading documentation
5. Debugger – if there isn’t an obvious solution from the previous steps, use the debugger of your IDE. Put breakpoints at relevant places and trace the flow of the program. This will help you understand how exactly the program functions (again, even if it is your code). You will be able to monitor variables and fields, and see if their values are not the ones you expect
6. Decompiler / framework source code – I’m always having a decompiler plugin installed on my IDE. It extends the process of looking at your own code to looking at all the code that’s involved. Alternatively, you can download/check-out the sources of the framework you are using (if it’s open-source) and add them to your IDE. Debugging with either the decompiled sources or the real sources can provide even more beneficial information about the problem, if you look at the appropriate places
7. Finally, if you haven’t solved the problem – ask a question. In the forums of the framework/tool, in general forums (JavaRanch, Sun forums, etc), or in dedicated Q & A sites like StackOverflow. State the question clearly, show what have you already done in order to find/fix it, and give the appropriate information (setup, version of the framework, the code in question, the whole stacktrace, etc). At the same time try not to make the question too long and try to emphasize the main points – people that aren’t paid to answer will be reading it after all
8. It sometimes happens that you have discovered a bug. This is a rare case with popular and mature frameworks/tools (yes!), but if you are sure it is a bug, go to the issue tracker and file a detailed bug report. They will either instruct you how to use a workaround, or will fix it eventually

I’ve used words like “relevant” or “appropriate”. The degree of benefit from each step will depend on your experience, and each time you will get better at each of the steps.

Don’t forget to share!

Reference: Tips for Identifying and Debugging Problems from our JCG partner Bozhidar Bozhanov at the Bozho’s tech blog blog.