"Refactoring" Book Club - Episode N-1

We are almost at the end. I lost count of which meeting this was since I missed a few in the early chapters of the refactoring catalog—this time, we discussed Chapter 11: Refactoring APIs. This chapter was the least inspiring or exciting. It didn't spark any captivating conversation, but it gave us time to discuss the book and its general approach to introducing these refactoring patterns.

The one thing worth noting, which I briefly highlighted in From Patterns to Frameworks, is Martin Fowler's effort in breaking down steps that most software developers consider muscle memory. By that, I mean we cobble together 5+ of these steps in one swoop, then check if anything breaks. There might be more productive ways to go about it, which is where, generally speaking, this book helps. It provides a detailed map of the refactoring steps to ensure you go from 0 to 100 without ever breaking anything. The frequent test-running habit supports ensuring that.

This is where some may get confused about the goal of the book (or these catalog chapters, to be precise). They are not recipes to be directly applied; developing the intuition on when they need to be used is your responsibility. It becomes clear when some of the patterns are the exact opposite of one another. They highlight the fact that the final choice of which path to take is up to the reader, and the book gives you the tools to help you make that decision. There were many trivial ones to review in this chapter, but there's still some valuable insight.

Isolate side effects whenever possible. "Historically", that's where most pain points arise; whenever side effects are hidden or mixed with other functionalities, it becomes harder to track down what causes the program to fall into a failed state. Clearly signaling when a function has side effects is a good communication habit, it might help trigger the reader's spidey sense. One of my favorite callouts was about the usage of boolean flags. Use them sparingly and not together back to back. When I see something like this:

const report = generateReport(entries, status, false, true, true, false);

I die inside a little bit. Now I have to check the function signature. This is generally not a big deal but it certainly introduces friction for someone reading through the code. I try to avoid this pattern as much as possible. A good intent that I share with the author is about making life easier for the caller. The snippet above is an example of the opposite of that.

Thoughts

Refactoring is a judgment call. Some cases are clear-cut; they are code smells that need addressing. Many other times, it's about you being able to find a good balance. Don't be afraid to make changes; even though I haven't had the chance to go about refactoring following the book's recommended steps, they are a good place to get started. A wrong refactoring will surface quickly as you go through the process. Overall, this chapter wasn't particularly illuminating; some of the observations are well put, but nothing new to me. I still enjoyed going through the various examples and would continue recommending this book to anyone doing active development.