Reference Graphs or 'Feature Sketches' as Tools for Refactoring Legacy Code

some of the code we work with at new relic has been around for quite awhile. unfortunately, not all of it has stayed clean and well factored over time. if you’re not careful, even the cleanest code can succumb to entropy. and without an active effort to counteract this, you can end up with code that seems unmaintainable.

luckily, there are some tools we can use to help us make clear, organized, testable changes to even the most complicated codebases. one of my favorites is the ‘reference graph’, a slightly expanded version of the ‘feature sketch’ described in working effectively with legacy code . the general idea is that you have a set of changes you want to make to your code, so you graph everything that holds any references to the changes you want to make.

let’s take a look at the following sample code, in which all the classes and even the methods on those classes are a confusing mess of crossed references:

class a
  def report
    b.new.get_all_the_state
  end
end
 
class b
  def get_all_the_state
    [ munge_state, @state1, d.new.get_state ]
  end
 
  def munge_state
    get_state
  end
 
  def get_state
    @state0
  end
end
 
class c
  def report
    d.new.get_state
  end
end
 
class d
  def get_state
    @state2
  end
end
 
module e
  def self.report
    [ a.new.report, c.report ]
  end
end

let’s say that we’ve decided that we want to get rid of the b#get_all_the_state method and split its responsibilities among the ‘a’ and ‘b’ classes. in this contrived example, it’s easy to prop up a canned solution that we should refactor toward. but in a more complicated project, it can be challenging to know all the ramifications that one simple change can have on your source code. by graphing the reference between the methods and instance variables around the code we want to change, we can get a good idea of the scope of the changes we want to make. a visual representation of what the references between methods and instance variables in your code can give you a good view of where your tightest knots of code are hiding and guide your work to untangle them.

i use graphviz to create the graphs. it renders images from dot files, which you use to define node, style them and define their associations. for the code above, this would be the dot file. once you’ve installed graphviz, you can create the graph below with this command:

all the parts we want to change are in red and all the parts that refer to parts we want to change are in orange. this gives us an idea of the scope of the changes we want, as well as a roadmap to getting those changes done incrementally. we see that we can’t make changes to b#get_state without also making changes to b#munge_state and b#get_all_the_state as well. the tests for these methods will also have to change or be removed entirely. the existing tests for the orange boxes should not have to change, but new ones will likely need to be written to cover the functionality of the old red boxes. neither code nor test changes for the black boxes should be necessary, since the orange boxes should isolate all the changes within their interfaces and keep them hidden from unrelated code.

as i work my way through the refactor, i go back to the dot file and keep it up to date with my changes. this is a great way to keep track of my progress and it keeps me from getting lost, which is a very real risk in large refactors of complex code. i like to check the graphviz dot file into source control. that way if i get stuck too badly, i can always go back to my graph and see if it’s still current. it’s also nice to be able to go back and look at your progress. the feedback you get from seeing changes in the graph can help you find areas for further development (this is similar to the feedback loop of tdd.) if the graph starts to get more twisted, you may need to rethink your code change.

once we’re all done, our graph should look like this:

the newly added green boxes are either new entries or old entries that are completed. at this point, our code should look like this:

class a
  def report
    [ b.new.zeros, ones ]
  end
 
  def ones
    b.new.ones
  end
end
 
class b
  def zeros
    @state0
  end
 
  def get_state
    @state1
  end
end
 
class c
  def report
    @state2
  end
end
 
module e
  def self.report
    [ a.new.report, c.report ]
  end
end

while contrived examples are nice for demonstrating a concept, they don’t do a good job showing how well this technique works in practice. in my experience, it takes about two to three hours to construct the graph for a non-trivial tract of code. i consider it time well spent and i find keeping it up to date as i work is surprisingly unobtrusive. in fact, i actually look forward to making my incremental changes then seeing the graph clean up and straighten out as i work.

recently, i overhauled the configuration system in the ruby agent. here’s a teaser:

if you’re curious, the dot file for these graphs can be found in the git history for the ruby agent .  you can browse through the history and recreate the graph at each point.

if you’d like to find out more about this subject, i encourage you to read michael feather’s book for more information on this and other techniques for working with code that’s suffered the ravages of time and entropy.