Inlining code for clarity
Programming styles come and go, in fact I believe they just get recycled from previous eras of computing and then reinvented for the modern age. I’m certain that a lot of modern principles are not new discoveries but actually ideas investigated and subsequently rejected by our predecessors generations of programmers ago.
I think back to the days when I coded COBOL and I remember huge long fan-fold listings of my program laid out on floor in my hallway. I’d be on my hands and knees with a biro working my way down it trying to find a bug. You would start at the top and work your way down making notes in the margin about what data was being pushed through and how you expected the code to manipulate it.
I’m a huge fan Robert C. Martin, he has a wealth of experience and knowledge and he’s also fun to watch, presenting topics in a way that make sense and resonate. He has been credited with defining the single responsibility principle (SRP) which according to Wikipedia is defined as:
The single responsibility principle states that every module or class should have responsibility over a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class. All its services should be narrowly aligned with that responsibility.
Robert C. Martin
The intention of this principle is pretty clear; don’t complicate your code by making one element do many things. Doing that would make your code harder to reason about and difficult to maintain.
I’ve heard programmers over the years talk about SRP and I’ve seen it applied a multitude of times in the applications I work on. It works. It is a great idea. If followed to the Nth degree though it becomes counterproductive though. I’ve seen code where SRP is applied not only applied to classes and module, but also to methods. Each method has a single purpose. The end result being an awful lot of small functions.
Let’s take an example. You want to write a method that calculates your your total inventory value. The algorithm is simple; read items from the DB, pull out the values, aggregate them, transform into a data structure for display and return that data structure. Applying SRP to that we would end up with 5 functions; a top level function that calls 4 other methods and returns the result from the last function call. The 4 methods then read from the DB, pull out values, aggregate and transform respectively. You can read the top level function and clearly see what it does just but reading the methods names it calls. Simple.
Why is that a problem? Well, imagine taking your favourite novel and creating a webpage from it. Now take each paragraph and make that a hyperlink to another page. Where you have similar paragraphs throw some parameters on to the hyperlink so that when you arrive at that page it has the right context. Finally, let those paragraph pages call other paragraph pages. Could you possible imagine attempting to read that and follow the story? I can’t.
I work on large corporation applications that are often well-established, complicated and written by programmers with totally different approaches and who normally don’t work on it any more. I’ve seen SRP applied to methods and then the methods they call, the end result is a huge spaghetti mess that challenging to follow, difficult to reason about and very risky to change.
My standard approach to this mess is firstly to write some tests and second; refactor it. And I start by inlining absolutely everything I can. The more I inline, the clearly it generally becomes. Quite often I’ll end up with one function that you read from top to bottom and it totally makes sense what it is doing. Where I have code that is clearly duplicated I may pull out some functions but I’m guided by readability.
Applying SRP to functions reduces clarity in my opinion. I would rather read a single method that makes the purpose clear. My job as a programmer is to add value to the applications I work on. To do that I need to understand what the code does and how I can change it. Anything that gets in the way of that is counterproductive and I believe we should avoid it.
In conclusion; try inlining, you might find that your code gets simpler and its intention clearer. If you find yourself kneeling on your hallway floor trying to read 12 foot of fan-fold perhaps you’ve gone to far though.