UEXAnalysisTools72

Date: 5 MAR 2012 Author: Petr Somol, Jan Lahoda

Contents

Motivation

NetBeans 7.2 will integrate the external library FindBugs.

Currently: menu Refactoring->Inspect and Transform opens this dialog, where user selects the scope of analysis and selects which inspections to perform.
Currently: inspections available in Inspect and Transform can be overviewed in this dialog.
Currently: if an active inspection has identified an issue, the Refactoring window is displayed in the form including the preview of proposed code changes (as diff). Selecting which issues to correct and clicking on Do Refactoring changes the code.
Currently: if only passive inspections have identified an issue, the Refactoring window is displayed in the simpler form without refactoring preview as no refactoring is due (Do Refactoring should be in fact disabled).
Currently: if the previous Inspect & Transform result is still displayed with refactoring preview active, and the user invokes another Inspect & Transform process, then the previous Refactoring windows gets into invalid state as marked by NEEDS REFRESH.

With the upcoming addition of FindBugs support to NetBeans 7.2 it is desirable to review the UI of all NetBeans analysis tools. Jan points out that currently (including the not-yet-public FindBugs support) there are three related tools with similar UI, related functionality, related use-cases, accessible from different places, as over-viewed in this section.

Notation: In the following passive inspection will denote an action that identifies issues but does not affect the source code in any way, active inspection will denote an action that in addition to identifying issues does provide the option to refactor (but may be used just passively).

Refactoring -> Inspect & Transform

Opens a dialog allowing to specify the scope of analysis (active file, project, all projects etc.) and to choose inspections (i.e. what to analyze), single or groups of them as defined in "configurations". Each inspection covers some issue in java code like potential bugs, performance patterns, redundancy, bad practice, clarity of code, etc. (e.g., Unused imports, Final declarations in final classes, Invoking Thread.run() instead of start(), etc.). Inspections can be passive, i.e., just outputting information about the respective findings or active, i.e., providing the option to automatically refactor code to fix the respective issue. Inspections or configurations can be managed in a dedicated Manager dialog, where available inspections are presented in hierarchical view, and for each inspection a description is given.

The button Inspect opens a dockable window "Refactoring" with a hierarchical view of identified issues. If only passive inspections have identified issues, the window shows just the hierarchical view. If an active inspection has identified an issue, then the right half of the Refactoring window shows in diff what transformation is proposed as a result of the inspection. User can let the changes be done using the Do Refactoring button under the hierarchical view.

Sources -> Code Analysis

(Under development) Opens a dialog very similar to Inspect & Transform. Its main purpose is to make available additional inspections from the external package FinBugs providing static analysis tools as well as NB internal passive inspections. All provided inspections are passive (see above). The dialog also displays the Install button in case FindBugs support module is missing.

The button Run Analysis opens a dockable window "AnalysisResult Window" with a hierarchical view of identified issues. The right half of the window shows html-formatted description for the issue in focus.

Tools -> Analyze Javadoc

Currently: Analyze Javadoc opens Analyzer window and hierarchically lists all identified issues for the current file. Selecting which issues to correct and clicking on Fix Selected changes the code.

Does not open any dialog but immediately analyzes the current file.

Opens a dockable window "Analyzer" with a hierarchical view of identified issues. No diff is shown, the issues are described just inline in the tree hierarchy. A click to Fix Selected button does the refactoring.


Changes in NetBeans 7.2

The goal is to introduce FindBugs functionality and streamline the UI of analysis tools.

Extent of Tools' Unification

The idea of unifying all analyzers under a single UI workflow is to be considered. The alternative proposal separates passive inspections from active ones. In such case, a separate dialog Code Analysis for all (both passive and active) inspections would be accessible from menu Source while only active inspections would be gathered in what has so far been the Inspect and Transform dialog under menu Refactor.

Approach 1: Providing a Separate Workflow for Passive Inspection

  • Separate workflows allow for UI better crafted for the intended purpose: for code analysis, ability to sort by category (or even priority) of a warning is crucial, while that may not be critical for a refactoring tool. Having only one type of results (either warnings or code changes) in one window would look more natural. Also the I&T dialog wouldn't be cluttered with analyzers that do not provide any refactorings.
  • The Code Analysis is intended to be language-agnostic, while I&T is Java-only. Having Inspect&Transform without any transformations in non-Java distributions seems strange. Making a "custom" transformation tool (similar to the current I&T sans passive inspections) language agnostic might be a future effort, though.
  • Follows existing principles: there are separate Find Usages and Rename actions, having two separate workflows is somewhat similar.
  • Javadoc analyzer checkbox "Fix on Next" may have an established use-case: gradual adding of missing Javadoc, where user clicks Next, then edits the newly added Javadoc in editor, then click Next, then edits next newly added Javadoc, etc. It might be possible to add Fix on Next "checkbox" to the I&T, and may actually be useful for other code transformations as well. Implementability check pending.

Approach 2: Unifying the Workflow Of All Analyzers

  • The functionality of all three existing analyzers is so closely related, that their separation actually might be considered as unnatural. The differences in user interaction among the three analyzers are minor and easily resolvable. (jlahoda: if we find a way to merge Analyze Javadoc into Inspect&Transform without breaking some important user usecases, that would be very good. But having a separate action&"window" for code analysis and for code refactoring/transformation is a separate matter. Lets ignore Analyze Javadoc for the moment.)
  • Preventing multiple similarly looking windows (where their difference of purpose is not strikingly clear) open at once under the editor is better avoided to save screen space and to ease user orientation.
  • Separating passive and active inspections can be done in two ways: a) providing mutually exclusive sets of inspections in passive and active workflows, or b) providing a passive workflow providing the passive functionality of all existing inspections and an active workflow providing only the active inspections. In case of a) this creates a usability gap: the user wants to inspect code using all existing inspections, without initially caring whether the tools would eventually help with refactoring or not. With separated dialogs users would need to call two series of inspections from different menus, to obtain results split in two result hierarchies. To review the found issues she would then need to browse the source files twice to see each identified issue. In case of b) this would not be a problem, but the active inspections would be accessible from two different places, once in their passive form and once in the active form, with no shortcut from the passive to the active workflow once the user is amidst the passive one.
  • It may still be necessary to bridge Code Analysis to Inspect&Transform partially, to support this usecase: the user finds a warning (which is accompanied with a fix), and wants to fix the warning (semi-) automatically over the whole project. May be resolvable through a pop-up menu action (implementability check pending). In the 'joint' action approach this could be resolved by sorting by category and "unchecking" everything except the required category.

Approach 2 is considerably more far-reaching than the task of adding FindBugs support itself. Due to the extent of necessary changes and remaining open questions the complete unification of analysis/transformation workflow is postponed after 7.2. For details see UEXAnalysisToolsUnified. The proposal below follows Approach 1.

FindBugs Integration in NetBeans 7.2

FindBugs inspections and existing NB inspections in passive form will be accessible through menu Source->Inspect...

Inspect Dialog

The Inspect... action opens an Inspect dialog, providing UI similar to that of Inspect and Transform dialog. FindBugs functionality is accessible and configurable together with internal NB inspections through inspection configurations, or direct selection of particular inspections. Also the dialog contains the necessary additional UI elements like Install missing FindBugs support.

The proposed Inspect dialog closely follows the UI of Inspect and Transform.

Remark: to distinguish the internally and externally defined inspections use the wording "NetBeans Java Hints" and "FindBugs Static Analysis". Accordingly, Inspect and Transform should contain predefined configurations: All Inspections, NetBeans Java Hints, FindBugs Static Analysis.

Inspector Window

The button Inspect in Inspect dialog would opens the dockable Inspector window closely resembling the window produced by Inspect and Transform, but without the active UI components. The window is split to the left panel and right panel. The left panel shows the hierarchical list of all identified issues. Issue type (bug, warning, bad practice, performance) is marked by icons (FindBug issues would have a different icon from the rest). All issues are listed by their short one-line description. (Optional: long descriptions displayed as tooltips). The right panel shows full issue description.

Proposed Inspector window showing a mix of passive issues. The right panel shows a description for the focused issue.

Existing Workflow Issues To Be Resolved

  • Naming can be probably improved. Inspect & Transform results are presented in a window named Refactoring (in menu Window->Output this is listed as Refactoring Preview). Code Analysis results are presented in a window named AnalysisResult Window (not yet in menu Window->Output). Analyze Javadoc results are presented in a window named Analyzer (under the same name in menu Window->Output).
  • Question: is there any overlap in inspection functionality between current NB implementation in Inspect & Transform and the external FindBugs library ? If so, duplicates would be better prevented (depending on FindBugs presence)
  • Javadoc Analyzer window provides checkboxes to enable "fixing on next" (fixing when browsing over issues in the list) and Go Over Fixed Problems. This is different from the other two analyzers.
  • Passive inspections are emphasized by Italic in Manage Inspections dialog, but this convention is not followed elsewhere. A consistent way of distinguishing passive from active visually on inspection name should be defined.

Inspect & Transform Specific

  • Passive inspection names are presented in Italic (in Inspect & Transform dialog but not elsewhere) have in their description a disproportionately large "Refactoring: No associated refactoring" sentence.
  • Description issues. The result hierarchies often contain items named Missing description. Many inspection descriptions are confusing or missing. See the enclosed image for "Missing description" issues:
    Issues described as "Missing description"
  • in only passive inspections have found issues, the Refactoring window does not present any diff as there is no code change to reviewed/applied. But the button Do Refactoring is still displayed and enabled; when pressed, nothing happens and the window just closes. See the enclosed image:
    Button Do Refactoring is erroneously enabled even if there is no refactoring due
  • if more than one refactoring is applicable to a found issue, then a warning dialog is displayed, e.g.
    Warning if multiple refactorings are applicable for a single issue
    After it is closed and user proceeds to the Refactoring window, there is no further indication visible in the displayed hierarchy or diff about this unambiguity, yet it is still present in form of several issues listed for the same line as is the case in the following image:
    Multiple issues described as "Missing description" represent mutually exclusive refactorings applicable to a single line of code
    Note that the diff preview window shows the possible effect of only the first possible refactoring. Now the Refactoring window misleadingly allows to select multiple of these mutually exclusive refactorings and to press Do Refactoring. As a result only the first one is applied.
  • When the Refactoring window is marked as NEEDS REFRESH, then clicking some of the buttons in the left vertical toolbar erroneously restores this window's original contents and re-enables Do Refactoring button without actually doing refresh.

Code Analysis (FindBugs) Specific

  • FindBugs integration: the Install button currently installs the NB FB support module, but not the FindBugs library itself. More user guidance may be needed to prevent confusion.
  • FindBugs support is under development with many issues remaining to be fixed (html description formatting, dialog guidelines conformance, etc).

Analyze Javadoc specific

  • Analyze Javadoc does not allow to specify the scope of analysis - restricts by default to current file only



TODO: Review all issue type icons

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo