COMP 310

Debugging in Eclipse

    Current Home  Java Resources  Eclipse Resources

 Let's face it, even the best programmers create code that, well, doesn't quite perform as expected. Debugging is an extremely important skill that all developers need to know.  

One can get a long way with simple "println debugging" where one simply prints out various values of interest at particular spots in the code.   This debugging technique can be very useful when one just wants to get a status check without interrupting the execution of the program.  

But there are times when one needs a bit more than a simple string printed to the console window.   Luckily, Eclipse provides some powerful debugging tools to help out.


Debugging in a Nutshell

Basically, debugging is a way of pausing the execution of a program so that we can examine its internals at that point in time to deduce what is going wrong.   We can also gain manual control over the program execution at that point.  To that end, we have a few basic notions:

Breakpoints:   These are locations in the code that we can specify where code execution will stop and we can examine the execution environment and gain manual control over the execution process.   Setting a breakpoint in Eclipse is as simple as right-clicking on the desired line of code.   There are fancy, less used, versions of breakpoints called "conditional breakpoints" where execution stops only if certain conditions are met.    In support of breakpoints are two main control buttons:

Variable Inspection:   Once execution has stopped by a breakpoint, we can examine all the variables, fields and objects that are in scope (visible) at that moment.   Eclipse has a very nice "object inspector" for this job.

Execution Stepping:  This manual control over the execution process allows us to advance the execution one line of code at a time.   Eclipse provides convenient buttons for stepping control.  There are generally 3 flavors of stepping that one uses most commonly:


This page is not designed to be a definitive reference on debugging in Eclipse.  For more detailed, official information please see the documentation included in Eclipse or this web reference to the Debug Perspective.


Eclipse Debug Perspective Screen Shot

Click for full-size image
Debugger screen, annotated


Note:  The first time you run the debugger a dialog window will pop warning you that Eclipse wants to switch to the Debug Perspective.  Sometimes this dialog window is hidden behind your application, so be on the lookout for it.  Since that's clearly what we want to do, check the box that says not to remind you again and it won't bother you any more.

Descriptions of the Highlighted Items Above

Run Debug Button

The green bug-shaped button near the top of the Eclipse window starts the debugging process, starting up the program as normal but enabling the breakpoints.   Clicking on the normal green "Run" button will cause the program execution to ignore any breakpoints.


See the box labelled "Last Breakpoint" in the screenshot.   These little green dots show where program execution will suspend and allow you to take control.  You may have as many of these in your code as you desire.  If you are not sure where your code goes, put breakpoints at all the possibilities so you can catch the execution whatever it does.      The breakpoint that caught the latest execution suspension has an arrow on it.

To set a breakpoint, simply right-click the left-most column in the code file, either on or just to the right of the vertical scrollbar.    Select "Toggle Breakpoint" to insert or erase a breakpoint.   Select "Enable/Disable Breakpoint" to activate or deactivate a breakpoint without erasing it.

List of Breakpoints

You can see where all your breakpoints are by clicking the tab marked "Breakpoints".    All of the breakpoints in your project will be shown here and you can erase, activate or deactivate them easily here without having to dig through your code to find them.   You can also jump directly to the breakpoint spot in your code by double-clicking the breakpoint in the list.

Current Line of Code

The line where execution is currently suspended is highlighted in green.  The highlighted line is the one that is will be executed next.   The highlighted line has NOT been executed. 

Outline View of Current Code Location

This is a different viewpoint on where execution has been suspended.   The outline view shows the location in terms of what method inside of what class the suspended line is located.   This is a higher level view than looking at a single line of code buried in possibly a multitude of syntax.

Call Stack of Current Thread

Rather than two previous syntax-based views of the location of the suspended execution, the call stack gives us a temporal view of our location.    The call stack, reading from top to bottom, tells us where we are in terms of what methods are being called by what other methods at what points in their code.   In OO systems where abstract entities are being passed from object to object, it can be very difficult to know where any given method is being invoked from.   Likewise, a chain of delegations can get very long and complicated making it difficult to tell if it is correct.     Clicking on each line of the call stack will take you to the line of code that is currently involved in the delegation chain, aiding greatly in our understanding of what is happening at that moment.

Object Browser

The object browser allows us to inspect the values of all fields and variables that are in scope at that moment.   If a field or variable references an object, the object browser allows us to look inside that object to see its internal fields and if those fields reference objects, we can dig even deeper.   This enables us to see all the values that could affect us at that moment plus be able to trace through a chain of connected objects.  

Since the visibility of fields and variables changes depending on where one is, what one can see changes depending on where we look on the call stack.   Clicking on a different level of the call stack brings different fields and variables into scope and we can explore them as well.    Amongst other things, this enables us to check method parameter values to see if methods were called with the correct values, a common source of errors.

Run to Next Breakpoint

The "Resume" button is the icon with the samll yellow rectangle and green triangle.  Clicking this will cause program execution to resume from its suspended state, continuing on until the next breakpoint is encountered.

Run To Line  (Ctrl-R,  also on both the right-click and main "Run" menus)

Another useful option will cause the system to run up to, but not execute the line upon which the cursor sits.   This is equivalent to placing a breakpoint on the cursor's line and clicking the "Resume" button, except that it doesn't litter your system with unnecessary breakpoints.  (Note: any breakpoints encountered along the way will cause the system to pause, as normal.) 

End Program

The red, square "Terminate" button will immediately end the program whether it suspended or not at the moment.   Use this button when you want to stop program execution because there is nothing further to be learned by continuing on or if the program is unable to continue on because of errors.

 There is a "Suspend" button (double vertical yellow bars -- obscured in the above screen shot) that will immediately suspend the executing code, but in practice it is very difficult to get code to suspend in any useful location, so this button has limited utility.

 Step Into

This button will execute the next executable statement of code, which is not necessarily the entirety of the current line.   Technically, "Step Into" advances to the next step of the semantic reduction of the current line, i.e. it will step into the inner-most method called in that line of code.   The stepping process may progress through many nested method calls before it completes the execution of the current line.   The "Step Into" process is identical to the process of hand-evaluating an expression.

Step Over

This button will treat the current line as an atomic calculation and will fully execute the current line of code and move to the subsequent line of code without going into any nested method calls.   This button is useful when you are confident of the operational veracity of all of the nested method calls on that line.

Step Out Of

This "Step Return" button will cause execution to complete whatever the method the current line of code is located in.   Execution will suspend at the next line of code after the current method's call, i.e. the next line of code in the next outer level in the call stack.   This is useful when you are confident that the current method will complete successfully.  (Or if you accidentally stepped into a method that you wanted to step over!) 


Basic Debugging Procedure

There is really no "one right way" to debug.   Debugging is as much an art as it is a skill.  One has to think like a detective, looking for clues and applying deductive reasoning to explain what you've found.   Always remember that the location at which bugs manifest themselves as some sort of visible effect, is often not where the problem actually occurs.  You must always keep an understanding of how all the pieces in your system relate to eachother.  

Most debugging scenarios can be broken down into these steps:

  1. Set breakpoints at key locations in your code.  Typical places to put breakpoints:
  2. Examine  all the variable that are visible at the breakpoint location and make sure that their values are what you expect them to be. 
  3. Step slowly through your code, checking all your variables as you go.. Watch for the unexpected!  Remember, if you code did what you expected, it would have run without any errors. 
  4. Use Step Over and Step Return (Step Out Of) only when you are positive, i.e. you already did a Step Into at least once already, that everything that is being skipped works properly.   It is very common to get over-confident and miss where an error occurs because one has skipped right over the critical code.
  5. Add more breakpoints when you see something amiss and you deduce that an error might be due to potential problems in another section of the code.  You can use the "Resume" button to quickly advance to the next breakpoint.





© 2017 by Stephen Wong