Using Structure101 to Improve the Design of Your Code

In this technical blog coder-in-residence Viktor Nordling describes how Structure101 is an awesome (albeit expensive) tool for significantly improving code quality (and why you should use it).

Background

I recently started working on a greenfield project. As you all know it’s always fun and games in the beginning, but after some time things usually start to get a bit messy. After a year or so it can seem that starting a new project would be alot more fun than maintaining the inexplicably horrible legacy project you’ve been working on. This time I was determined not to let this happen. In order to prevent code from becoming “instant legacy” you need a way to get an overview of what the code structure actually looks like, and a way to measure if it’s getting better or worse. Structure101 is an analysis tool from Headway Software that does just that.

Actual Architecture

By this point I already had the basic structure of the code in place, so I was really curious as to what Structure101 would say about it. Here’s a screenshot of what Structure101 reported about the first version of my code:

This is an architecture diagram, which Structure101 generates based on how the code actually hangs together. Experience suggests that this is likely to be markedly different from the architecture that an architect may have at some point in time optimistically drawn in a fancy modelling tool. One layer in the diagram is only allowed to use layers below it. The arrows in the diagrams indicate violations against the architecture.

If you open up the interfaces layer (package) you see the following diagram:

Fixing the Flaws

So we have four violations in total, two from the interfaces layer. There are a number of techniques to fix a violation. These include:

1. Moving the dependant to the dependee’s package (or vice versa);
2. Extracting an interface from the dependee’s class and placing in a layer below the dependant’s layer; or
3. Refactoring the code so that the dependency no longer exists.

In the case of the StateChanger above, I could simply move it to the states package. It actually felt like it belonged there more than it belonged in interfaces.

In case of the notifier, it depended on a Player class in entities. I extracted an interface from this class and placed it in the interfaces package.

The dependency from entities to states actually pointed out a code smell. I was shortcutting my state pattern when I scheduled the start of a new hand. I knew when I wrote it that it was wrong, but this violation pushed me to actually fix it.

The dependency from entities to util was similar. I had made an instance variable in a class default to a NullNotifier (which was in the util package), in order to be able to test my code without having to inject this from the test. I solved this by creating a static utility method in my test code that injected mock objects into my class under test.

Once this was done my software architecture in Structure101 looked like this:

Keeping it Clean

Once you’ve reached a point where you have an architecture that you like, the key point is to keep it this way. In my case, I was the only programmer on the project however I knew that more developers would be joining soon.

In order for others in your team to adhere to the architecture you’ve carefully laid out, it’s vital that they actually know (in a pragmatic way) what that architecture is. Structure101 comes with a neat plugin (for Eclipse and IntelliJ) which will show you the architecture diagram inside your IDE. And here’s the pragmatic part — if you introduce a dependency that violates the software architecture the compilation will actually fail. Here’s a screenshot of what that looks like:

If you select the “Architecture” tab, you see the violation graphically in the diagram:

You can also get the Structure101 Build component (including an Ant and Maven plugin) which will check for violations during the build phase. However this component comes with a hefty price tag of US$1,500.

Loaded with Legacy

If you are working on a project with a lot of legacy code getting down to zero violations in one go might be a herculean task (and is probably not even recommended). In this case you can configure the plugin to only fail the compilation in case of new violations. Then at least we know that we aren’t making things worse.

Structure101 comes with a web application for showing information about your project. By publishing snapshots of your project continuously you can maintain a good graphical overview of how the project is evolving. Here’s a screenshot of some of the graphs from the web app in regard to architectural complexity:

Here we can see that the excess complexity (XS) has gone down to zero. We also see a breakdown of the different types of contributors to the excess complexity. The reason why the “size” is reduced in the final version is because I excluded some 3rd party code (which contributed to the Fat/method complexity).

Summary

Structure101 is a great tool, although in my opinion slightly overpriced. The support that is included in the price is excellent. I do think code all around the world could smell a little bit less if more people knew about this product, so please spread the word. There’s a 30-day trial that you can sign up for to try it out today!

—
Viktor is a freelance software engineer who occasionally finds coding serenity at the Agile Digital office.