Tools to learn somebody else's codebase

Writing code can be a difficult task, but reading it is usually even more challenging. Here's a quick tip to help you the next time you want to make sense of a bunch of code you don't yet know.

My day job is working support for JBoss. If you haven't noticed, JBoss doesn't let much moss collect-- projects are constantly moving, improving and springing up from the ground. If you want to keep up in this environment, you'd better learn to read code and digest it quickly-- and that's the need that produced this solution.

One of the things I like to do is add a quick function to my .profile (we'll see how to use this in a bit):

# Use this with 'tree'. Works with wildcards
getF() { THF=`find . -name $1`;export THF; /usr/bin/gedit $THF & }

I'd use this in conjunction with Linux's excellent 'tree' command. Use 'tree' to quickly see what the source base looks like, then use getF() to easily zero in on files that are of interest.

Let's go with an example. Today I'm looking at the just-released droolsjbpm-integration package (which looks good, and runs some neat examples out of the box, by the way.) So I might start like this:

rick:~/Tools/droolsjbpm-integration-distribution-5.2.0.M2/examples$ tree
.
|-- binaries
| `-- droolsjbpm-integration-examples-5.2.0.M2.jar
|-- runExamples.bat
|-- runExamples.sh
`-- sources
|-- pom.xml
`-- src
|-- main
| |-- java
| | `-- org
| | `-- drools
| | `-- examples
| | |-- broker
| | | |-- BrokerExample.java
| | | |-- Broker.java
| | | |-- BrokerServices.java
| | | |-- events
| | | | |-- EventFeeder.java
| | | | |-- EventGenerator.java
| | | | |-- EventImpl.java
| | | | |-- Event.java
| | | | |-- EventReceiver.java
| | | | |-- EventSource.java
| | | | `-- StockTickPersister.java
| | | |-- misc
| | | | `-- Utils.java
| | | |-- model
| | | | |-- Action.java
| | | | |-- Company.java
| | | | |-- CompanyRegistry.java

(More deleted. You get the picture, though. Get the picture.... get it? Hee hee.)

So we immediately get a view of what's in the codebase. You might see how much code is out there.....

rick:~/Tools/droolsjbpm-integration-distribution-5.2.0.M2/examples$ find sources -name *.java | wc -l
46

So only 46 java artifacts. Pretty reasonable.

If a codebase has a lot of interfaces and inheritence, it can be a little tougher to read. So we might have a look at how much of that is out there....

rick:~/Tools/droolsjbpm-integration-distribution-5.2.0.M2/examples$ find sources -name *.java |xargs egrep 'implements|extends' |wc -l
24

Hmmm, that seems a little rich, for only 46 java files. It could be that you're working with a framework built to allow lots of things like plug-ins and alternative implementation (in a good case) or it could be that you're reviewing code written by someone who reads too many academic textbooks and doesn't really grasp the proper use of such abstractions. In this case, I'm confident it's the first case.

OK, so now let's see how that function we put in .profile can be put to use:

rick:~/Tools/droolsjbpm-integration-distribution-5.2.0.M2/examples$ getF Cell*
[3] 2514

Immediately, my text editor pops up showing me Cell.java, CellState.java, CellGridCanvas.java, CellGridImpl.java, and CellGrid.java.



I grant you, much of this is also available via a nice IDE like JBDS or Eclipse, but sometimes (well, frequently, really) it's hard to wrangle the projects into an IDE without doing a bunch of classpath setup, dependency downloads, etc.

Happy Code Reading!