Suggestions Tutorial

Overview of Suggestions

The Suggestion plugin is a software exploration tool that finds code elements that are relevant to the task at hand. By analysing the contents of a concern (a set of program elements pertaining to a particular software behaviour) created with the ConcernMapper plugin (see below), the Suggestion plugin finds elements that are structurally related to those in the specific concern and ranks them according to their relevance.

The relations analyzed to generate suggestions are:

• for each method in the specified concern: which methods call it, which methods it calls and which fields it accesses;
• for each field in the concern: which methods access it.

Basic Use

Creating a Concern Model

Using the Suggestion plugin requires first constructing a concern model using the ConcernMapper view. The contents of the ConcernMapper view represent a concern model, which is made of up multiple concerns. The following view shows a single concern, which has no elements assigned:

New concerns are added using the new-concern button ; you will be prompted for a name for the concern. Elements are added to the concern by dragging and dropping fields or methods. It is generally helpful to give a concern a useful name, usually describing the behaviour being investigated. Concerns can be renamed by right-clicking on the concern.

Generating Suggestions

Having built part of a concern using the ConcernMapper, the Suggestion plugin may be used to generate additional suggestions. This done by dragging a concern and dropping it on the Suggestions view. Alternatively, clicking the Suggest button will generate suggestions for the concern that is currently selected in the ConcernMapper view.

Once the suggestions are generated, it is possible to sort them by name, degree, or related element by selecting the apropriate column in the Suggestions view. Elements whose degree is below a specified level can be filtered out using the Filter button. Elements that are deemed relevant can then be moved into the appropriate concern in the concern model by obtaining the context menu on a suggestion and selecting Move to concern model.

The Suggestions View

The Suggestions view displays the suggested elements. The view has three columns:

• Element: The name of the element that is suggested.
• Reason: The reasons for which this element is suggested.
• Degree: The degree to which the suggested element is deemed relevant by the tool.

The Sugggestions Toolbar

The Suggestions view has two buttons.

• : Generate suggestions for selected concern.
• : Filter out elements whose degree is below a certain threshold.

The Suggestions Preferences

To access the preferences for the Suggestion plugin, select Preferences from the Window menu on the eclipse menu bar. In the left pane expand the ConcernMapper node and select Suggestions.

The Suggestions preference page allows to set the filter on or off and to set its threshold degree.

Try it!

1. Create a new concern called decomposition.
2. Find org.jhotdraw.standard.AbstractFigure and drag its decompose() method to the decomposition concern.
3. Cause the Suggestion plugin to make suggestions. Examine the list of resulting elements and drag any applicable ones onto the concern.
4. Repeat!