Eclipse FindBugs Plug-in Features Document

Synopsis

The Eclipse FindBugs Plug-in provides a seamless integration of FindBugs into Eclipse 3.0 and up. The user can decide whether bugs will be detected automatically (this is achieved using an incremental builder, see xxx) or on demand by clicking on a button or invoking FindBugs from a context menu. It is importasnt to note that the Eclipse FindBugs Plug-in does not try to mimick every aspect of the FindBugs Swing frontend. Rather, it tries to adhere to the Eclipse user interface guidelines (see Eclipse website yyy) as much as possible. Thus, Eclipse users will find it most natural to work with FindBugs, which will increase user acceptance.

Supported platforms

The Eclipse FindBugs Plug-in has been initially been targeted at Eclipse 2.x. However, as Eclipse 3.0 is out now and offers some real helpful enhancements, future versions of the plug-in will support Eclipse 3.x only.

Features

Core functionality

Finding bugs

The user can choose among the following options how to find bugs in the current project:

Invoke FindBugs manually for the entire project

Invoke FindBugs manually for a package and all subpackages

Invoke FindBugs maually for a single class

Automatically invoke FindBugs upon saving a file

Options 1 through 4 require the user to start FindBugs manually. The plug-in will provide context menu entries (labelled „Find bugs“), main menu items (I suggest Source -> Find Bugs, but we should discuss Search -> Find Bugs as well). Additionally, the plug-in provides a button the user can add. This button will run FindBugs on the current selection, be it a project, a package or a class.

Option 4 will utilize the Eclipse incremental resource builder facility in order to check bugs for the project each time the user saves a file. This is the most seamless integration, as it will work similar to the normal compiler behaviour which finds syntax errors as you save.

Bug list

The plug-in will create a marker for each bug that has been found by the FindBugs engine.

Markers show up at various location in Eclipse: first and most important, they show up in the Java editor. A little icon will be displayed in the annotation bar on the lefthand side of the editor. Also, a little colored box will be displayed in the overview ruler on the righthand side of the editor. Additionally, markers will be listed in the problems view (this is new for Eclipse 3.x, formerly tasks and problem were listed in the tasks view). The problems view features a filter dialog that can be used to define various filter criteria, e.g. „Show only markers of that type, show only a certain number of markers, show only markers whose severity is critical and the like.

While it is certainly a good idea to use markers to mark bugs, several FindBugs users have requested that the various types of bugs should be displayed with different icons. This feature request can not be realized using the problem view, since this view will only display three different icons, based on the severity of the respective marker (error, waring, info).

In order to realize this feature request (and also to realize some additional features), the next version of the Eclipse FindBugs plug-in will feature its own bugs view that show all bugs on a project in a similar fashion as the problems view. The plug-in will make sure that the FindBugs bug markers will not show up on the problems view. However, as some users may find using the problems view more natural than using the bugs view, using the bugs view should be configurable in the plug-in preferences.

The bugs view will show the following information about each bug:

bug icon

bug accuracy indicator

bug pattern short description

class name

package

line number

The context menu for each bug will show the following entries:

Description...

Change accuracy to...

Accurate, important

Accurate, unimportant

Inaccurate

The bug view will also need to have a filter dialog similar to the one of the problems view that lets the user decide which bug warning are to be displayed.

Additionally to the filter options that are available on the filter dialog of the problems view, the user may choose which accuracy levels he wants to see. This way, the user can hide all false positves from the view, concentrating on fixing the real bugs. If he made a mistake while classifying a bug, he can turn off the filter to see the bug again.

Question: even if you hide certain warning types from the problems view, the markers will still be visible in the code editor. Is this the behaviour we want to mimick for our bugs view?

Bug Histories

TODO: write a clever summary of Dave's and Bill's article.

User Classification of Warning

The user may edit the accuracy of a bug warning. The plug-in supports the following ways of doing so:

Using the context menu of a bug entry in the bug view. Select the appropriate entry from the "Change accuracy to..." sub menu.

Inplace editing the bug entry in the bug view. Each bug entry has an accuracy indicator, which basically is a little icon representing the accuracy of the bug warning. When the user clicks into the cell containing this icon, a dropdown appears, letting the user choose a new accuracy.

Configuration

Configuration of the Eclipse FindBugs plug-in will take place globally and per project.

Global configuration

The user can configure the following aspects:

Whether bugs will be listed on the bugs view or on the problems view

Define detector sets. A detector set is a named group of activated bug pattern detectors. The decision which detector set(s) will be run on the project, will be made on the project configuration.

Project level configuration

The user can decide:

Whether FindBugs will automatically scan the project for bugs each time a file is saved.

Which bug detector sets will be run.

I suggets the following screen layout:

[ ] Enable FindBugs

(*) Run all detectors ( ) Select detector set

Detector set name	enabled
Sample name	[x]
Sample set 2	[ ]
Sample set 3	[x]

If the „Enable FindBugs“ check mark is disabled, the other controls will be disabled as well. If the „Run all detectors“ radio mark is set, the table will be disabled, and all detectors will be run. If the user enables the „Select detector set“ radio mark, he will be able to select any number of detector sets which will the be run on the project.

Getting Help

General Help

The user can open the help dialog by clicking Help -> Help Contents. The general help will consist of the FindBugs manual. It will be rendered into an Eclipse Help plug-in automatically by way of the docbook stylesheets.

Plug-in Help

Additional help on the Plug-in itself will also be presented to the user in the online help system. The additional parts will just be inserted into the main FindBugs manual, to keep documentation maintenance easy.

Bug pattern help

It is quite essential that the user can retrieve additional information on each bug pattern. There are many ways to achieve this:

The user presses F1 while in the bug view. The plug-in will automatically open the Eclipse Help with the explanation of the bug pattern. This behaviour can be achieved using the context help feature of Eclipse.

A context menu entry (labelled "Description") is added to the context menu of the bug view. When the user selects this entry, the help system opens and displays the appropriate bug pattern description.

Another way is the bug description view that has been contributed by Phil. It opens up when the user clicks on a bug marker (currently, this does not work quite well under Eclipse 3.0). Additionally, we could make this view appear when the user clicks the context menu entry ("Description...") of a bug pattern entry in the bug view.

Personally, I feel that the last option is quite un-Eclipse-like and prefer options one and two. As this may be a matter of taste, I suggest that we offer all three options to the users and let them decide which ones to use by adding a suitable entry to our (yet to be written) preferences page.

Peter Friese

2004-09-18T19:48:58