Reading Clean Code Week 5: Boundaries
I’m back to reviewing Clean Code this week after last week’s blog on Refactoring. And while the chapter I’m reviewing this week is short, the concept is incredibly important. This week I’m talking about boundaries, the way we incorporate code that we did not actually write into our systems.
At a mere eight pages, Clean Code’s chapter on boundaries is one of the shortest in the book. But while the advice is relatively concise, in my opinion your ability to cleanly integrate third-party code into your applications will make or break your success as a developer.
Every software engineer, almost regardless of their experience, has been there, painstakingly staring at a computer screen trying to find a bug. Your program isn’t working as expected, and you can’t for the life of you figure out why. Worse yet, sometimes your program does work as expected, even though you know the code is broken. This nightmare scenario happens to the best of coders, but clearly something is wrong here.
Although we’ve all written bugs into our programs, sometimes integrating third-party software introduces bugs that we didn’t write! Imagine spending hours staring at your computer screen, your eyes getting bleary, your frustration mounting, and this bug isn’t even your fault!
Well, it’s not all your fault. You may not have written the bug in the culprit code, but failure to exercise good boundaries in your programs is no one’s fault but your own. Luckily, Clean Code’s (and chapter author James Grenning’s) recommendations on boundaries can help protect your code from potentially buggy and broken software. By designing our programs in a way that protects from outside error, you keep your code more maintainable and can avoid some of those agonizing debugging sessions.
In truth, boundaries present something of a double-edged sword for web developers. On the one hand, building software in a team and being able to rely on others to help you write code can significantly improve your engineering experience. I’ve written about this a bit in my earlier web developer days, but using external packages saves you the time of writing that code. In addition, working with third party code allows you to rely on potentially more experienced and more talented developers to meet some of you software needs. For instance, you may need to hit an external API to acquire data for your application, or maybe there’s a Ruby gem for complex math that’s perfect for your use case. After all, there’s a reason open source software has been so useful for engineers.
On the other hand, as Clean Code says, “There is a natural tension between the provider of an interface and the user of an interface.” While users have specific needs of what they want their code to do, providers of third-party packages strive for broad applicability.
So what can you do to establish good boundaries for your program? The first thing you should do — and I promise this is not satisfying for a software engineer passionate about web development — is read. Instead of clacking away at your computer, read documentation about the external API or library you’re using. Slow down, take your time with it, and acquire deep understanding of the tool you want to use. Maybe even write a couple of internal tests (what Clean Code calls “Learning tests”) to check if the software works as desired. Only after learning and exploring this outside code should you feel comfortable exposing your system to it.
Another method for handling the boundaries of your programs is introducing wrappers/adapters for external code. By introducing adapters into our code, we limit our dependencies. By limiting your program’s references to that third-party code, you limit the likelihood that your programs will break. I really liked the following podcast for its overall discussion of boundaries, but I thought it was especially insightful for information on how to “push the weird stuff to the edges of our code.” Frankly, the hosts do a better job than I can of explaining why boundaries are so important for writing clean code. I highly recommend you listen.
Finally, and I don’t mean this to sound trite, but exercise common sense when managing third-party boundaries. By common sense I mean maybe skip the library that hasn’t been updated in several years or that API with the skimpy, confusing documentation. Let’s look at the following code from a project I’ve been coding to get a better sense of what I mean here:
While I’m working with lots of external code in this project, I’m fairly certain I’ve not overexposed my code here. One way I can be sure of that is I’m primarily using popular, well-documented projects like Redis and TypeGraphQL. These projects have many contributors as well as thorough documentation, so if I run into an unexpected bug I won’t be grasping in the dark trying to figure it out.
One other thing I’ve done here is physically grouped my third-party software imports together, away from code I’m importing from within my own application. While not strictly a principle of maintaining clean boundaries, it follows the Clean Code rule of Conceptual Affinity, the notion that certain parts of code should be more closely grouped to things they resemble. Using a package manager like yarn also helps maintain my external code.
Remember, Clean Code is not just about writing code that a computer can read, but what a human can read. As such, your code has to communicate your ideas clearly, and nothing muddles what you’re trying to say quite like someone else saying it for you. Rather than letting third-party libraries interject for your code, limit what these programs can say, and protect the overall cleanliness of your code.
