Review Structural Changes in Java Code

Code reviews are a proven practice to help keep your code as clean as possible. Doing it means nitpicking every detail of each method and class: naming, length, responsibility, algorithm, style, and so on. You have to look at everything used to ensure that lines of code are understood not only by the machine (compiler) but also by humans. As humans, you or your fellow programmers will have to maintain the code.

What about the bigger picture? Well, there’s the architecture of the system. Perhaps, it just sits with the leads of your team, or perhaps it is properly documented, but generally, people know which applications or microservices are integrated with each other and in what direction the data flows between them. Somebody cares about this highest level of modularity.

You may also like: Java Code Review Checklist

But I think there’s a gray area between those two: the method and class level changes, and the whole system architecture changes, namely the inner composition of a single application or microservice. Or to be more precise, the composition of a lump of code that is built together as a unit. For a lack of a better word, let’s call it a module.

Looking After the Composition of Modules

Granted, nowadays, everybody uses microservices. If each module is really small, and if it contains only a couple dozen classes or so, the composition of the module doesn’t matter. Maybe, you don’t even bother grouping the module’s classes into separate packages.

But if you do, for example, if you do monolith-first development, or if your microservice is not so micro, then you should care how the code inside your module is structured. In the first case, you do this so that you have clearly defined components constituting your monolith that can be later promoted to microservices, without risking that your code will become a big ball of tangled classes. In the second case, you do this just to be able to work on one component at a time, without having to understand the entire big module.

To assure this, you need to keep an eye of how the classes are grouped, and how those groups of classes — components — depend on each other:

So, do you analyze package declarations and import statements while you are reviewing code changes? I bet you don’t!

When writing code, you just type the class name, and the IDE kindly adds the import statement for you. You don’t notice that you’ve just added a new dependency between components. When reviewing code, out of habit, you typically skip this seemingly boilerplate information without a second thought.

Tools to the Rescue

That’s why I’ve written Socomo. This is a tool that screams at you when a new component has been added, or more importantly, a new dependency has been introduced. It does so by keeping a socomo.html file with such information in your project, which changes along with the code. This way, in a single commit, besides actual code changes, you’ll see the higher-level view of structural changes, like so:

A similar principle about functionality is also provided by this commercial product Softagram. It integrates with your version control system, and to each pull request, it adds a report with a summary of the impact of the changes:

You can even go a step further — proactively guard composition changes by declaring the rules of the composition and using tools like ArchUnit to enforce them:

Though sometimes it can be hard to know upfront how the code should be structured, the composition of an application or service is a kind of emergent design. So please, keep an eye on it while you're adding more code so that the design emerges in the correct direction.

I hope you enjoyed!

Further Reading

Java Code Review Checklist

Code Review Essentials