“Everyone has different learning styles” says my wife the teacher.  I think this also applies to how we look at code.  I tend to be a big picture person and need to understand the lay of the land before I can dive into the details.  What are the architectural layers? How is the code structured? What are the main components of the application?  One would think this would be obvious across similar domains, but it’s suprisingly not.  When diving into a new codebase it’s often very handy to be able to get a big picture view quickly.  One easy way to do so is with a sequence diagraming tool that can generate a sequence diagram for you.  One such tool is Object Aid.

Object Aid provides two plug-ins for Eclipse: a class diagramming tool and a sequence diagramming tool.  Both can reverse engineer from your code.  The class diagramming tool is free, the sequence diagramming tool is an inexpensive $19 at the time of this writing.  This is the best bang for your UML buck I’ve found.  Register on their site to get a free trial.

Installation is easy, so we’ll skip that and dive right in.

Class Diagrams

Class diagrams are saved as files within any of your Eclipse projects.  They can sit right alongside the code  in your source tree, in a seperate folder in your project or in a separate project on it’s own.  I generally use one of the latter two approaches.  If one keeps a class diagram within a package in the source tree that would indicate to the poor sap maintaining your code that the diagram contains only classes from the package it’s saved in.  That’s not likely to be a very useful or interesting diagram.

Creating a class diagram is a simple matter of creating a new file in Eclipse.  Once done, you can drag any class visible in Eclipse to the diagram.  Associations will automatically displayed between classes that have them.  Tip: in the project explorer or navigator view keep the “sync with editor option” unselected. Otherwise when you start to drag a class that class will become visible in the editor if it happens to be open.

There are lots of visibility options you can explore.  Here’s a sample class diagram:

Sequence diagrams

The fun really starts with sequence diagrams.  This is my secret weapon when I’m looking at a new code base.

Sequence diagrams can be generated from many different sources:

• manually in the diagram by dragging a message from a lifeline, by selecting a method, or dragging a method from the project explorer or navigator views.
• java stack trace console
• debugger stack frames
• dragging methods from the call hierarchy view

The most useful to me is from the debugger.  Quite often one know the entry point to a server call.  From there stepping through the code dives deeper into the code.  Once in the target class it can be tought to see the forest from the trees.  Here’s where the sequence diagram shines.

In a new sequence diagram right-click the debugger stack and select “add to sequence diagram”.  The entire stack frame will be put on the diagram.

On very complex apps, especially those using JEE or Spring there are often quite a lot of layers and proxy classes.  These are not very useful in a sequence diagram.  In the preference one specify filters and filter the unwanted classes from the diagram.