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 refactoring.  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 values:

When a selection contains a conditional return, an arrow is drawn from the return statement to the left, crossing the beginning-to-end arrow:

When 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)