Clean Code Development | Integration Operation Separation Principle

This week, I had to add a new feature to a project that I started a whole year ago and didn’t touch for a pretty long time. When I first looked at my code that I considered pretty clean at the moment I wrote it, I was shocked, how inconsistent and unstructured it was. I had to invest a lot of time, just to get a clear understanding of what my code does.

Since I can’t always invest that amount of time, just to understand, what i wanted to express with my code, I took a look at some Clean Code Strategies. The one, that I found most important was the Integration Operation Segregation Principle (IOSP).

What is Integration Operation Segregation

IOSP (Integration Operation Segregation Principle) is a Clean Code strategy, that allows us to clearly separate between integration code and operational code. It allows us to systematically reduce the complexity of large methods into much simpler ones.

Integration Methods only compose other units (including other Integration Methods) but do not contain any logic.

Operational Methods just contain logic and never integrate any other functional Methods. They should be really small, composable and easy to read.

How to apply this principle

If you have big methods or just messy methods in general, you can apply this pattern in just a few simple steps.

Find big methods that do operational and integration tasks at once
Split them up into smaller methods
Classify your methods as either Integration Methods or Operational Methods

If you aren’t sure, if a method is integrational or operational, the method needs to be split up even more. If you did that right, you should now have a really easy to read integration method, that implements the other methods.

Example

Here I have a small example class with just one big, junky method in it. On the first sight, you can’t really see what this function is all about. You can see the title of it, but what it actually does inside, is really difficult to tell.

In the first step, we can extract a new function from line 14. This function could be called generateKrokiImage() since it calls the generateImage() function of the krokiAdapter.

Next, we can extract a new function from line 11 to 16, and call it something like replaceAdocDiagramWithKroki() . This function replaces the old value that was found by the regex, with the new one that got generated by our generateKrokiImage() function.

The next function we can extract sits on lines 8to 10. It walks thru the whole file tree and checks each item, if it really is an asciidoc file and matches the given regex. We can call this function forEachAdocFile() .

Lastly, we have a really easy to understand function, that is well structured and maintainable. It could look something like this:

As you can clearly see, the convert function is the only integration method in this class, and is the one, that gets called from the outside. All the other private methods are operational.

Reflection

What went good

The actual implementation of the principle went really good and was pretty straight forward because of the refactoring methods of IntelliJ IDEA.

What needs improvement

First, I didn’t really get the purpose of this pattern, because in the end, the code was longer, than it was before (because of the whitespace between different methods). I got a little confused by that and had to ask my mentor. After a quick discussion, he cleared things up and it was clear to me, that with this way, you can see on the first sight, what the whole class or method does.