A common criticism of loosely coupled code is that it’s harder to understand. How do you see the big picture of an application when loose coupling is everywhere? When the entire code base has been programmed against interfaces instead of concrete classes, how do we understand how the objects are wired and how they interact?
In this post, I’ll provide answers on various levels, from high-level architecture over object-oriented principles to more nitty-gritty code. Before I do that, however, I’d like to pose a set of questions you should always be prepared to answer.
Mu
My first reaction to that sort of question is: you say loosely coupled code is harder to understand. Harder than what?
If we are talking about a non-trivial application, odds are that it’s going to take some time to understand the code base – whether or not it’s loosely coupled. Agreed: understanding a loosely coupled code base takes some work, but so does understanding a tightly coupled code base. The question is whether it’s harder to understand a loosely coupled code base?
Imagine that I’m having a discussion about this subject with Mary Rowan from my book.
Mary: “Loosely coupled code is harder to understand.”
Me: “Why do you think that is?”
Mary: “It’s very hard to navigate the code base because I always end up at an interface.”
Me: “Why is that a problem?”
Mary: “Because I don’t know what the interface does.”
At this point I’m very tempted to answer Mu. An interfaces doesn’t do anything – that’s the whole point of it. According to the Liskov Substitution Principle (LSP), a consumer shouldn’t have to care about what happens on the other side of the interface.
However, developers used to tightly coupled code aren’t used to think about services in this way. They are used to navigate the code base from consumer to service to understand how the two of them interact, and I will gladly admit this: in principle, that’s impossible to do in a loosely coupled code base. I’ll return to this subject in a little while, but first I want to discuss some strategies for understanding a loosely coupled code base.
Architecture and Documentation
Yes: documentation. Don’t dismiss it. While I agree with Uncle Bob and like-minded spirits that the code is the documentation, a two-page document that outlines the Big Picture might save you from many hours of code archeology.
The typical agile mindset is to minimize documentation because it tends to lose touch with the code base, but even so, it should be possible to maintain a two-page high-level document so that it stays up to date. Consider the alternative: if you have so much architectural churn that even a two-page overview regularly falls behind, then you’re probably having a greater problem than understanding your loosely coupled code base.
Maintaining such a document isn’t adverse to the agile spirit. You’ll find the same advice in Lean Architecture (p. 127). Don’t underestimate the value of such a document.
See the Forest Instead of the Trees
Understanding a loosely coupled code base typically tends to require a shift of mindset.
Recall my discussion with Mary Rowan. The criticism of loose coupling is that it’s difficult to understand which collaborators are being invoked. A developer like Mary Rowan is used to learn a code base by understanding all the myriad concrete details of it. In effect, while there may be ‘classes’ around, there are no abstractions in place. In order to understand the behavior of a user interface element, it’s necessary to also understand what’s happening in the database – and everything in between.
A loosely coupled code base shouldn’t be like that.
The entire purpose of loose coupling is that we should be able to reason about a part (a ‘unit’, if you will) without understanding the whole.
In a tightly coupled code base, it’s often impossible to see the forest for the trees. Although we developers are good at relating to details, a tightly coupled code base requires us to be able to contain the entire code base in our heads in order to understand it. As the size of the code base grows, this becomes increasingly difficult.
In a loosely coupled code base, on the other hand, it should be possible to understand smaller parts in isolation. However, I purposely wrote “should be”, because that’s not always the case. Often, a so-called “loosely coupled” code base violates basic principles of object-oriented design.
RAP
The criticism that it’s hard to see “what’s on the other side of an interface” is, in my opinion, central. It betrays a mindset which is still tightly coupled.
In many code bases there’s often a single implementation of a given interface, so developers can be forgiven if they think about an interface as only a piece of friction that prevents them from reaching the concrete class on the other side. However, if that’s the case with most of the interfaces in a code base, it signifies a violation of the Reused Abstractions Principle (RAP) more than it signifies loose coupling.
Jim Cooper, a reader of my book, put it quite eloquently on the book’s forum:
“So many people think that using an interface magically decouples their code. It doesn't. It only changes the nature of the coupling. If you don't believe that, try changing a method signature in an interface - none of the code containing method references or any of the implementing classes will compile. I call that coupled”
Refactoring tools aside, I completely agree with this statement. The RAP is a test we can use to verify whether or not an interface is truly reusable – what better test is there than to actually reuse your interfaces?
The corollary of this discussion is that if a code base is massively violating the RAP then it’s going to be hard to understand. It has all the disadvantages of loose coupling with few of the benefits. If that’s the case, you would gain more benefit from making it either more tightly coupled or truly loosely coupled.
What does “truly loosely coupled” mean?
LSP
According to the LSP a consumer must not concern itself with “what’s on the other side of the interface”. It should be possible to replace any implementation with any other implementation of the same interface without changing the correctness of the program.
This is why I previously said that in a truly loosely coupled code base, it isn’t ‘hard’ to understand “what’s on the other side of the interface” – it’s impossible. At design-time, there’s nothing ‘behind’ the interface. The interface is what you are programming against. It’s all there is.
Mary has been listening to all of this, and now she protests:
Mary: “At run-time, there’s going to be a concrete class behind the interface.”
Me (being annoyingly pedantic): “Not quite. There’s going to be an instance of a concrete class which the consumer invokes via the interface it implements.”
Mary: “Yes, but I still need to know which concrete class is going to be invoked.”
Me: “Why?”
Mary: “Because otherwise I don’t know what’s going to happen when I invoke the method.”
This type of answer often betrays a much more fundamental problem in a code base.
CQS
Now we are getting into the nitty-gritty details of class design. What would you expect that the following method does?
public List<Order> GetOpenOrders(Customer customer)
The method name indicates that it gets open orders, and the signature seems to back it up. A single database query might be involved, since this looks a lot like a read-operation. A quick glance at the implementation seems to verify that first impression:
public List<Order> GetOpenOrders(Customer customer)
{ var orders = GetOrders(customer);
return (from o in orders
where o.Status == OrderStatus.Open
select o).ToList();
}
Is it safe to assume that this is a side-effect-free method call? As it turns out, this is far from the case in this particular code base:
private List<Order> GetOrders(Customer customer)
{ var gw = new CustomerGateway(this.ConnectionString);
var orders = gw.GetOrders(customer);
AuditOrders(orders);
FixCustomer(gw, orders, customer);
return orders;
}
The devil is in the details. What does AuditOrders do? And what does FixCustomer do? One method at a time:
private void AuditOrders(List<Order> orders)
{ var user = Thread.CurrentPrincipal.Identity.ToString();
var gw = new OrderGateway(this.ConnectionString);
foreach (var o in orders)
{ var clone = o.Clone();
var ar = new AuditRecord
{ Time = DateTime.Now,
User = user
};
clone.AuditTrail.Add(ar);
gw.Update(clone);
// We don't want the consumer to see the audit trail.
o.AuditTrail.Clear();
}
}
OK, it turns out that this method actually makes a copy of each and every order and updates that copy, writing it back to the database in order to leave behind an audit trail. It also mutates each order before returning to the caller. Not only does this method result in an unexpected N+1 problem, it also mutates its input, and perhaps even more surprising, it’s leaving the system in a state where the in-memory object is different from the database. This could lead to some pretty interesting bugs.
Then what happens in the FixCustomer method? This:
// Fixes the customer status field if there were orders
// added directly through the database.
private static void FixCustomer(CustomerGateway gw,
List<Order> orders, Customer customer)
{ var total = orders.Sum(o => o.Total);
if (customer.Status != CustomerStatus.Preferred
&& total > PreferredThreshold)
{ customer.Status = CustomerStatus.Preferred;
gw.Update(customer);
}
}
Another potential database write operation, as it turns out – complete with an apology. Now that we’ve learned all about the details of the code, even the GetOpenOrders method is beginning to look suspect. The GetOrders method returns all orders, with the side effect that all orders were audited as having been read by the user, but the GetOpenOrders filters the output. In the end, it turns out that we can’t even trust the audit trail.
While I must apologize for this contrived example of a Transaction Script, it’s clear that when code looks like that, it’s no wonder why developers think that it’s necessary to contain the entire code base in their heads. When this is the case, interfaces are only in the way.
However, this is not the fault of loose coupling, but rather a failure to adhere to the very fundamental principle of Command-Query Separation (CQS). You should be able to tell from the method signature alone whether invoking the method will or will not have side-effects. This is one of the key messages from Clean Code: the method name and signature is an abstraction. You should be able to reason about the behavior of the method from its declaration. You shouldn’t have to read the code to get an idea about what it does.
Abstractions always hide details. Method declarations do too. The point is that you should be able to read just the method declaration in order to gain a basic understanding of what’s going on. You can always return to the method’s code later in order to understand detail, but reading the method declaration alone should provide the Big Picture.
Strictly adhering to CQS goes a long way in enabling you to understand a loosely coupled code base. If you can reason about methods at a high level, you don’t need to see “the other side of the interface” in order to understand the Big Picture.
Stack Traces
Still, even in a loosely coupled code base with great test coverage, integration issues arise. While each class works fine in isolation, when you integrate them, sometimes the interactions between them cause errors. This is often because of incorrect assumptions about the collaborators, which often indicates that the LSP was somehow violated.
To understand why such errors occur, we need to understand which concrete classes are interacting. How do we do that in a loosely coupled code base?
That’s actually easy: look at the stack trace from your error report. If your error report doesn’t include a stack trace, make sure that it’s going to do that in the future.
The stack trace is one of the most important troubleshooting tools in a loosely coupled code base, because it’s going to tell you exactly which classes were interacting when an exception was thrown.
Furthermore, if the code base also adheres to the Single Responsibility Principle and the ideals from Clean Code, each method should be very small (under 15 lines of code). If that’s the case, you can often understand the exact nature of the error from the stack trace and the error message alone. It shouldn’t even be necessary to attach a debugger to understand the bug, but in a pinch, you can still do that.
Tooling
Returning to the original question, I often hear people advocating tools such as IDE add-ins which support navigation across interfaces. Such tools might provide a menu option which enables you to “go to implementation”. At this point it should be clear that such a tool is mainly going to be helpful in code bases that violate the RAP.
(I’m not naming any particular tools here because I’m not interested in turning this post into a discussion about the merits of various specific tools.)
Conclusion
It’s the responsibility of the loosely coupled code base to make sure that it’s easy to understand the Big Picture and that it’s easy to work with. In the end, that responsibility falls on the developers who write the code – not the developer who’s trying to understand it.