Refactoring Annotations help programmers understand violations of refactoring preconditions.
Refactoring is an important part of building and maintaining
software. Refactoring tools guarantee semantics preserving
program transformations, but the user interface to refactoring tools is
lacking. Specifically, we have found that when a refactoring
cannot be applied (that is, when a precondition is violated),
refactoring tools to a poor job of communicating the problem.
Refactoring Annotations seek to communicate the consequences of a
refactoring to a programmer.
Refactoring Annotations are implemented as a plugin for Eclipse (download
When you select a piece of code to be extracted, and then press Alt+Shift+N
, Refactoring Annotations display information about a specific Extract Method
Each variable is assigned a distinct color, and each occurrence is
highlighted. Across the top of the selection, an arrow points to
the first use of a variable that will have to be passed as a parameter
into the extracted method. Across the bottom, an arrow points
from the last assignment of a variable that will have to be
returned. L-values have black boxes around them, while r-values
do not. An arrow to the left of the selection simply indicates
that control flows from beginning to end.
These annotations are intended to be most useful when preconditions are
not met. When the selection contains assignments to more than one
variable, arrows are drawn from the bottom as multiple return
a selection contains a conditional return, an arrow is drawn from the return
statement to the left, crossing the beginning-to-end arrow:
the selection contains a branch statement, a line is drawn from the branch
statement to its corresponding target:
If any of these preconditions are not met, Xs are displayed, indicating the location of the offending code.
Refactoring Annotations are preferrable to the standard, text-based refactoring errors because they:
- Indicate the location of errors
- Indicate errors relationally
- Indicate every error
- Distinguish types of errors at a glance
- Roughly indicate the amount of work required to recover from an error
- Distinguish showstoppers (Xs) from advisories (parameters coming in the top)