Why Abstraction is Really Important

Abstraction is one of the key elements of good software design.
It helps encapsulate behavior. It helps decouple software elements. It helps having more self-contained modules. And much more.

Abstraction makes the application extendable in much easier way. It makes refactoring much easier.
When developing with higher level of abstraction, you communicate the behavior and less the implementation.

In this post, I want to introduce a simple scenario that shows how, by choosing a simple solution, we can get into a situation of hard coupling and rigid design.

Then I will briefly describe how we can avoid situation like this.

Case study description
Let’s assume that we have a domain object called RawItem.

public class RawItem {
    private final String originator;
    private final String department;
    private final String division;
    private final Object[] moreParameters;
    public RawItem(String originator, String department, String division, Object... moreParameters) {
        this.originator = originator;
        this.department = department;
        this.division = division;
        this.moreParameters = moreParameters;

The three first parameters represent the item’s key.
I.e. An item comes from an originator, a department and a division.
The “moreParameters” is just to emphasize the item has more parameters.

This triplet has two basic usages:
1. As key to store in the DB
2. As key in maps (key to RawItem)

Storing in DB based on the key
The DB tables are sharded in order to evenly distribute the items.
Sharding is done by a hash key modulo function.
This function works on a string.

then we’ll distribute the items based on some function and modulo:

String rawKey = originator + "_"  + department + "_" + division;
// func is String -> Integer function, N = # of shards
// Representation of the key is described below
int shard = func(key)%N;

Using the key in maps
The second usage for the triplet is mapping the items for fast lookup.
So, when NOT using abstraction, the maps will usually look like:

Map<String, RawItem> mapOfItems = new HashMap<>();
// Fill the map...

“Improving” the class
We see that we have common usage for the key as string, so we decide to put the string representation in the RawItem.

// new member
private final String key;

// in the constructor:
this.key = this.originator + "_" + this.department + "_"  + this.division;

// and a getter
public String getKey() {
  return key;

Assessment of the design
There are two flows here:
1. Coupling between the sharding distribution and the items’ mapping
2. The mapping key is strict. any change forces change in the key, which might introduce hard to find bugs

And then comes a new requirement
Up until now, the triplet: originator, department and division made up a key of an item.
But now, a new requirement comes in.
A division can have subdivision.
It means that, unlike before, we can have two different items from the same triplet. The items will differ by the subdivision attribute.

Difficult to change
Regarding the DB distribution, we’ll need to keep the concatenated key of the triplet.
We must keep the modulo function the same. So distribution will remain using the triplets, but the schema will change and hava ‘subdivision’ column as well.
We’ll change the queries to use the subdivision together with original key.

In regard to the mapping, we’ll need to do a massive refactoring and to pass an ItemKey (see below) instead of just String.

Abstraction of the key
Let’s create ItemKey

public class ItemKey {
    private final String originator;
    private final String department;
    private final String division;
    private final String subdivision;

    public ItemKey(String originator, String department, String division, String subdivision) {
        this.originator = originator;
        this.department = department;
        this.division = division;
        this.subdivision = subdivision;

    public String asDistribution() {
        return this.originator + "_" + this.department + "_"  + this.division;


Map<ItemKey, RawItem> mapOfItems = new HashMap<>();
// Fill the map...
    // new constructor for RawItem
    public RawItem(ItemKey itemKey, Object... moreParameters) {
        // fill the fields

Lesson Learned and conclusion
I wanted to show how a simple decision can really hurt.

And, how, by a small change, we made the key abstract.
In the future the key can have even more fields, but we’ll need to change only the inner implementation of it.
The logic and mapping usage should not be changed.

Regarding the change process,
I haven’t described how to do the refactoring, as it really depends on how the code looks like and how much is it tested.
In our case, some parts were easy, while others were really hard. The hard parts were around code that was looking deep in the implementation of the key (string) and the item.

This situation was real
We actually had this flow in our design.
Everything was fine for two years, until we had to change the key (add the subdivision).
Luckily all of our code is tested so we could see what breaks and fix it.
But it was painful.

There are two abstraction that we could have initially implement:
1. The more obvious is using a KEY class (as describe above). Even if it only has one String field
2. Any map usage need to be examined whether we’ll benefit by hiding it using abstraction

The second abstraction is harder to grasp and to fully understand and implement.

do abstraction, tell a story and use the interfaces and don’t get into details while telling it.

Linkedin Twitter facebook github


The Single Responsibility Principle


What is SRP?
The term was introduced by Robert C. Martin.
Here’s the PDF paper for SRP by Robert C. Martin https://docs.google.com/file/d/0ByOwmqah_nuGNHEtcU5OekdDMkk/

From Wikipedia:


From Clean Code:



Why SRP?

  • Organize the code
    Let’s imagine a car mechanic who owns a repair shop.

    How would it be easier to organize the tools?
    Few drawers with different types in each one of them?
    Or, many small drawers, each containing a specific type?


  • Less fragile
  • Low Coupling
    More responsibilities lead to higher coupling.
    The couplings are the responsibilities.
  • Code Changes
    Refactoring is much easier for a single responsibility module.
  • Maintainability
  • Testability
    The “self documentation by tests” becomes much clearer.
  • Easier Debugging

What needs to have single responsibility?
Each part of the system.

  • The methods
  • The classes
  • The packages
  • The modules

How to Recognize a Break of the SRP?

  • Class Has Too Many Dependencies

    Another way too see many dependencies is by the test class.

  • Method Has Too Many Parameters
  • The Test Class Becomes Too Complicated
    It might suggest that some methods do too much.
  • Class / Method is Long
    Same goes for a class.
  • Descriptive Naming
  • Class With Low Cohesion

    A hint for a non-cohesive class:

  • Change In One Place Breaks Another
  • Shotgun Effect
  • Unable to Encapsulate a Module
    Suppose you use the @Configuration or XML configuration.
    The Configuration should hide any inner bean and expose minimal interfaces.

How to make the design compliant with the Single Responsibility Principle
They are also good for any Clean Code suggestion.
But here they are aimed for the Single Responsibility Principle.

  • Awareness
    This is a general suggestion for clean code.
  • Testable Code
    Write your code in a way that everything can be tested.
  • TDD
    (I am not going to add anything here)
  • Code Coverage Metrics
    Check the code quality metrics.
  • Refactoring and Design Patterns
    We’ll use composition and strategy instead of conditionals.
  • Clear Modularization of the System

Better design will be followed.

One Final Note