Feature Diagrams for Java

Every once in a while, someone asks me if there are any tools that they can use to make the class feature diagrams I described in Working Effectively with Legacy Code.  The fact is, when I create them, I just draw them by hand.  Recently, though, I decided to piece together a program that creates the diagrams automatically for Java classes.  It uses BCEL to grok class files, then it produces a dot file that can be piped into Graphviz.  The tool is kind of handy and I'll release it soon.

If you're wondering what feature diagrams are, here's a short description.  Feature diagrams are just pictorial representations of the dependencies inside classes.  They show internal "using relationships" among the class's methods and fields as a directed graph.  That might not sound like it's too useful, but it can be when you are looking at a class and deciding whether you'd like to refactor it.  It helps to see if there are already any natural cleavage points in the class.

Here's a feature diagram for the Parse class in the first release of Ward Cunningham's FIT testing framework:

The rectangles are  fields and the ellipses are methods.  Every arc indicates a use of one feature by another.  We can tell, looking at this diagram, that the size, leaf, and last methods calls themselves.  The at method is a little different.  There are actually several different overloads of at.  There's one with three arguments that calls another with two arguments, etc.  To keep the diagrams compact, there's only one node for every overloaded method.

Here's the Fixture class in FIT.  It's a bit different.  It contains a chain of method calls.  Subclasses of Fixture can override them to alter the way that tests are executed:

The parse method may look a bit odd hanging out there by itself, but it's just a method that isn't used by another method in the class.

The third piece of FIT is the TypeAdapter class.  It's a bit more complicated:

All of the ellipses that are bolded are public methods.  The non-bolded ellipses signify package private methods.  In this diagram you can start to see a bit of clustering.  There's a group of methods on the lower left that tend to work on fields named method, field, and target.  In the upper right, there are methods that work on fixture and type.  When this sort of thing happens, it's a bit like cell meiosis.  You can imagine the class sort of trying to split apart.  It's up to you to decide whether you want to formalize it by doing an extract class refactoring.

As I mentioned earlier, I've really only used these diagrams tactically when refactoring.  I never really had the time to evaluate parsers to write a tool for any particular language, but now that I have a tool to make them automatically, I'm having some fun.  You can learn a lot about a project by just calling up classes and looking at them in this way.  Some diagrams are nice and well proportioned like the ones above; others are an awful mess.  You can also tell pretty quickly what sort of a class you're looking at.  Data classes and utility classes are rather easy to discern, and uses of the template method design pattern tend to stand out also.

Comments

[Christian Schenk]

Sounds very interesting. I'm currently working on a project that needs a lot of refactoring and I can't wait to try it on some of the classes. The good old way of drawing these diagrams by hand just isn't very efficient (though effective).

How "soon" will you release it? What about a sneak preview?

[Levi]

Hi,

This tool looks like it would be interesting to use. Are then any updates on a possible release?

[Sandro]

This tool would be great for maintaining some of my legacy code! Has it been made public yet?

[Royd Brayshay]

Hi Michael,
I'm a great fan of your book and I like the manually drawn feature diagrams. If you want this type of thing from a tool couldn't you use something like NDepend or Lattix? The structure matrix diagrams they make can not be practically drawn by hand. Obviously the tool option also requires spending money.
Royd.

[Agustín Ramos]

Michael
Althought NDepend, XDepend or Lattix provide the same information that Micheal's diagrams when compared at the class level, I find feature diagrams more suitable for quick visualization. In the other hand, structure matrix diagrams are more suitable for analysis, for example by triangularization to find implicit modules and cyclic dependencies, and existing tools provide several levels of aggregation.
In the end I think feature diagrams are a MUST for XDepend and NDepend.

[Agustín Ramos]

Michael
Althought NDepend, XDepend or Lattix provide the same information that Micheal's diagrams when compared at the class level, I find feature diagrams more suitable for quick visualization. In the other hand, structure matrix diagrams are more suitable for analysis, for example by triangularization to find implicit modules and cyclic dependencies, and existing tools provide several levels of aggregation.
In the end I think feature diagrams are a MUST for XDepend and NDepend.