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)