Pure Danger Tech


Code Spelunking Techniques

18 Sep 2007

When trying to understand other people’s code, I find a few different techniques helpful. Since I’ve been doing this a lot lately, they’re fresh in my mind.

  1. Categorize class state – I find it is often helpful to classify the fields in a class into a few common categories (some of which may not exist):
    • Configuration – Configuration consists of properties (typically simple types) indicating how this class should behave. Configuration attributes are passed to the class (in constructor or via setter) and are often constant throughout the lifetime of the class.
    • Resources – Resources are typically other (complex) objects that are managing state or access to other components. Similar in ways to configuration but they tend to have a weightier feel to them. Often constant throughout the lifetime of the class.
    • State – State are attributes that hold the internal data pertinent to this class and typically change through the lifetime of the class. They may be initialized from configuration.
You may also see “derived” forms of all of these as well. Derived configuration may be computed (by converting seconds to milliseconds or a string value to an int or something). Derived resources may be obtained through the initial resources you are given. And derived state may compute properties (age) based on other properties (birth date). 

I find most attributes fall into these three broad categories. Separating the fields of a class into these three categories (and labeling them thusly) can be immensely helpful in understanding a class with a bunch of fields. </li> 

  * **Examine method callers / class users** &#8211; search for who is calling a method in an interface or class to see how it is being used. In Eclipse, you can either open the method call hierarchy (Eclipse: Ctrl-Alt-H) or search for references on a class or interface (Eclipse: Ctrl-Shift-G or Cmd-Shift-G). 
  * **Open method implementors** &#8211; often you will look at a method in an interface and want to look at one or more of the implementations of that interface method. The easiest way to do this in Eclipse is to highlight the method, open the quick hierarchy (Eclipse: Ctrl-T or Cmd-T), then pick an implementation of the interface. Eclipse will open the implementation AND put you in the implementation of the method you had selected. I only learned this trick recently but it&#8217;s made the world a better place.
  * **Project dependency diagramming** &#8211; sometimes its helpful to get the picture of project dependencies. You can find this information in the files of your IDE or build system. I have written crappy little programs to scrape it out of Eclipse .classpath and build XML files in the past. Generally, this shouldn&#8217;t take too long as it can be pretty quick and dirty. Then just build a [DOT file](http://en.wikipedia.org/wiki/DOT_language) like this: [source:java]
    digraph dependencies {

    &#8220;ui&#8221; -> &#8220;server&#8221;

    &#8220;tools&#8221; -> &#8220;server&#8221;

    &#8220;server&#8221; -> &#8220;data&#8221;

    &#8220;data&#8221; -> &#8220;common&#8221;
    and use any DOT viewer like [Graphviz](http://www.graphviz.org/) which will generate a dependency graph for you.
    <img height="100" src="http://puredanger.com/techfiles/test.png" />
    I find often there are projects like &#8220;common&#8221; that effectively everything depends on. Those projects generate a lot of lines but not much information, so I typically add a filter in whatever code I use to generate the .dot file to filter any dependency that includes common. That cuts down on the noise and helps bring out the real structure. 
    Of course the above pic is a toy example. Here&#8217;s a (partial) pic of the [Terracotta project dependency graph](http://puredanger.com/techfiles/deps.png), which is about mid-level complexity in stuff I&#8217;ve worked on. It&#8217;s messy but with not much effort you can get a pretty good idea how the code layers and where to look for the juicy stuff. </li> 
      * **Debug an example** &#8211; Walking through a running test can also be very enlightening on how things are put together. This is a good way to discover the run-time structure of the code (the last item tells you more about the compile-time structure). </ol> 
    I hope some of that was useful! I&#8217;m sure there are other techniques but these are the ones I&#8217;ve used the most recently.