A Single Responsibility

Over the years I quite often find myself pondering software development patterns and practices. It’s the kind of thing I think about in my downtime, when I’m driving to and from work, or sitting at home… pondering. I always seem to come back to one question, is the common interpretation of the pattern, that is how the majority of the world sees and implements it, what the author had intended? Is that inventor okay with it? It’s not like I’m going to solve this mystery today. One day I might have the opportunity to meet one of these greats and ask them. Is the outcome of their idea what they intended? I often times find myself reading coding, or working on past code where the implementation, doesn’t line up with my current interpretation of the pattern / practice. Though, upon talking about the code, or reading comments, or blind guessing. It can be clear that the intent was to implement towards a given pattern. In my last post, I talked about Separation of Concerns, which in my opinion can be closely related to, and often confused with the “Single Responsibility Principle“.

The intent of my last post, on Separation of Concerns, was to show that it in itself is not a pattern. It’s merely a practice that can be applied to thought, at any level. This can apply to your application at a macro level (application architecture), all the way down to the micro level (lines of code). Where I see things start to get fuzzy for people, is around the application into class level. The Single Responsibility Principle, is an embodiment of Separation of Concerns, but this embodiment is at a specific level. Unlike Separation of Concerns, Single Responsibility Principle applies only at the class level. I mean, that’s in the definition.

Classes should have a single responsibility and thus only a single reason to change.

But it’s like everything in software, open for interpretation. Patterns, Practices, and Principles fall victim to the subjective nature of application development. The real world of development rarely sees foo and bar, outside of whiteboard sessions. This means that you have to deal with real world objects, and real world problems. Then as developers we have to translate the canonical and sometimes naive FooBar examples, into our real world problems. Sometimes, more often than not, especially with less experienced developers, this leads to incorrect or harmful application of these principles.

Sometimes strict adherence to an interpretation of SRP and “Separation of Concerns”, can be deleterious to an application. The unfortunate nature of this, is that it’s a problem that doesn’t manifest until much later, when it’s too late. Now, I’m not trying to sit on my high-horse and say I don’t misapply these things. In fact, it would be foolish to think that anyone is perfect when it comes to this. I would be willing to bet that Martin Fowler himself doesn’t get it right 100% of the time. The difference is that with experience, you’re able to spot the blunder before it’s too late. Before you’ve gone to far, and you’re on the cliff being faced with a re-write. In the real world, this often times ends in a manager wishing he would’ve reviewed the code a little earlier, or a little more often. Hopefully, this post will help to clarify and add some litmus tests to the application of this principle.

First off, Separation of Concerns, isn’t SRP. If you think that, just forget it. Right now.

Separation of Concerns is the organization of thoughts, the ability to separate components, that are not overlapping, or mutually exclusive. Single Responsibility Principle, is an application of this practice, of grouping things that have the same concern, or reason for change into a single class. So it has a real world, level of application. It’s at the class level, that’s where you apply it…. And this is where the problem stems.

Say you have an application, you’ve got a Web Service that deals with incoming client web requests, and you’ve got an Auxiliary Service that is moving data to and from a database, and servicing long running system requests. This is an example of Separation of Concerns. This is not an example of Single Responsibility Principle. It’s too macro, we’re talking at our application level. Not at the class level. The problem that will stem from this form of thinking, is macro level class development. God classes. Sure — you have a class that represents your service that “Fulfills web service requests”. That’s his single responsibility… But is it? Is it really? If we imagine this mock class, he would have to

  1. Receive a message from the Web Server Service
  2. Parse said message
  3. Understand what to do
  4. Fulfill the request
  5. Build the response

Now, that’s definitely more than one responsibility! But from a macro level, it’s easy to see your class as having a single responsibility. You’re Separating your Concerns, remember?

In this case, it would probably make sense to have 1 class for building and parsing messages, 1 class that can switch on those messages to dispatch what to do, and 1 class for each of the actions to fulfill the requests. Woah. Woah. Woah. Wait just a minute. You just said 1 class for building and parsing… Isn’t that violating the SRP? Well, the answer as so many are in Software Development, is ‘it depends’. That statement, was intentional. It was meant to bring light to the fact, that the definition says “a single reason for change”. When you’re dealing with protocols, building and parsing can often be symmetrical. Therefor, if the protocol changes, that could be our single reason for change of this class. So it could be said to have a single responsibility of dealing with the protocol.

As you can see, where you focus the light of Single Responsibility will really play a factor into the organization and structure of your code. Just wait until you start shining that light too close.

When you start focusing the light at a micro level into your code. You’ll start to actually factor out responsibility.

Imagine you have a system, that is used to dispatch sms style messages, but it’s old school, so it takes time. You’ve got a client facing API called a MessageBroker, and a background service called a MessageDispatcher. Clients of your API deal directly with the MessageBroker, they give the MessageBroker in the format of

class Message 
{
public:
   enum RecipientTypes { Specified, Random }; 

public:
   const Address sender_;
   const Address recipient_;
   const RecipientTypes type_;
   const String &message_;
};

The intent, is that we give the MessageBroker the message, and he’ll do something with it for later pick-up by the MessageDispatcher. The MessageDispatcher will ensure delivery of the message to the recipient. Now, the API of the Message class is such that if you set the type, to Specified and set the address, the message will arrive at your intended target. However! If you set the type to Random, it should go to a random target. This randomness, isn’t really random, it could be based on a location heuristic.

You might think it’s best to define an interface for the message broker, and make it look something like this.

interface IMessageBroker 
{
    void Send(const Message &msg);
};

Then you might implement the IMessageBroker, something like this.

class MessageBroker : public IMessageBroker
{
public:
    void Send(const Message &msg)
    {
           // Validate the fields are appropriate for database
           ValidateFields(msg);
           // put it in the db
           Database.Store(msg);
    }

};

There you have it! Our SRP MessageBroker! He has a single responsibility. He accepts a message and stores it in the database. That’s it right? Well, you might be asking “What about sending to a Random recipient?” Yah — that’s not the MessageBroker’s responsibility… His responsibility is to “Accept” a message, and store it in the Database. It’s someone else’s responsibility to determine the recipient. /s

I hope even without the /s, you saw the sarcasm in that. But this is the reality of imposing SRP at a micro level. You’ve just shirked the responsibility of this class. He’s not anything more than a glorified secretary for the database. Worse yet, the real responsibility is now imposed somewhere it doesn’t belong.

Let’s say you require the client of your API to specify it. Well — you’ve just opened up a can of worms… Who’s to say they’ll use the same heuristic? They might have your carrier running all over Hell’s Half acre for the random recipient. Okay — force them to use a Utility class to generate the random. What you’re saying now, is that they have to remember to use your utility class to set the recipient. Or else… That’s not a very good design.

It makes sense, to put the responsibility, where it belongs. If calculation of a random recipient is the behaviour of how this system works. It only makes sense to put that logic into the MessageBroker.

class MessageBroker : public IMessageBroker
{
public:
    void Send(const Message &msg)
    {
        if(msg.type_ == MessageTypes.Random)
           msg.recipient_ = GenerateRandomRecipient(msg.sender_);

        // Validate the fields are appropriate for database
        ValidateFields(msg);
        // put it in the db
        Database.Store(msg);
     }

};

What’s curious about this, is that you can start to see you never needed the IMessageBroker interface in the first place. You see, the point of an interface is to be able to define a boundary of responsibility. Then have any implementation of that interface, provide that contract. Now, in our case, what’s our contract? Well, we get the Message somewhere where it can be dispatched. If it’s specified as a Random type, then we have to know to generate a random recipient, and get that to be dispatched. Would you get this out of the contract the IMessageBroker defines? I wouldn’t. So, for this design, it doesn’t make sense to have an interface. It’s a specific implementation, for a specific Message class. They’re very tightly coupled to each other. The behaviour expectation of your Message client, is very much dependent on the implementation behind that interface, implicitly. As you can see, his responsibility, really came to light once we took that step backwards, and looked at it for what it really was. (If you’re curious how I would do it differently, shoot me an e-mail!)

In summary, when you’re trying to apply the Single Responsibility Principle, it’s really important to focus your view at the right level. Take an objective look, and ask, what is this thing really doing? What would be reasons for me to make edits to this class? If you are honest, and you start to see that your class has many jobs. You can start to refactor some of those into their own classes, and compose that larger class of the smaller classes. Nothing says that Composition cannot occur with SRP. It just means your larger class’ job, becomes orchestration. There’s nothing wrong with that. The trap you don’t want to fall into, is shirking responsibility. You don’t want to start refactoring your code, where you’re pulling out responsibilities, and putting them on other classes. This will lead to a host of skeleton classes that are merely pass-through objects. The refactor in that case, is to look for the responsibility you’ve pushed on your clients. Ask yourself, should the client need to know that? If I was using this, and didn’t write it, would I know to do this? Those are the types of questions that you’ll find start to drive responsibility back into where they belong. That said, it’s a balance, and finding it is tough, it’s just a matter of practice.

I hope you enjoyed the post. As always — Happy Coding!

PL

“The price of greatness is responsibility” — Winston Churchill

 

Separating your Concerns

I spent a lot of time debating what I should title this post. Should it be “Buzz Words”? Or maybe “Separation of Concerns and SRP”… SOLID Concerns? In the end, I settled on this — Separating your Concerns. I also spent a bunch of cycles, asking myself what I really wanted to cover. What ideas do I want to convey? Then I spent some time thinking about how I would convey that message. What literary road would I take? From whom’s style would I borrow. However, none of this is of concern at this moment. The fact that it’s written is all that matters now.

I want you to think about the word, Organization, and what it means to you. Just take a moment to reflect on it.

When I think about Organization, I think about form, and about order. Organization makes me think about neatness, about cleanliness, and about space. Room to breath, and room to work. Organization to me is logical, it’s order — and the opposite of that is chaos, and anarchy. In our world, spaghetti.

Hold that thought.

Now, I want you to consider what “programming” is. What exactly is it for? What is a programming “language” for? Be specific.

You might think to yourself — “programming is telling the computer what to do.” Kind of. “A programming language is the syntax we follow to do that.” Kind of.

One of the definitions of “programming”, is the act of providing a computer (or machine) with with coded instructions for the automatic performance of a task. Now, that’s the definition of programming. But anyone who has worked on any project bigger than a hobby project, with multiple developers, knows it’s so much more than that.

Programming, not only is about telling the machine what to do. It’s doing it in a way that other people can understand it. It’s almost as if our programs are stories, and the compiler is the translator that turns it into instructions. The programming language, therefor is our medium of communication, between developers. Since, realistically the computer can’t understand C++ or C# directly. Consider for a moment, if we all had to “program” in CPU instructions written in binary, something a computer can understand directly. As soon as you have more than one person on the project, you’ve got a nightmare. It would be enough that the person has to communicate with the computer in that way, let alone with other developers. Trust me when I say, programming in higher level languages is for us, not them.

You might say “No. Comments are for communicating with other developers, and code is for the computers.”, to which I would reply simply “You’re wrong.” If you think that, I am sorry for you. (Actually, I’m more sorry for people who work with you.)

So programming, then is really a form of communication. It’s not completely unlike writing a story. This may seem like a bit of a Woo-Woo metaphor, but it helps to illustrate my point. Your tangled rats nest of notes you took in school, might’ve served its purpose for your studying. Though, it’s highly unlikely that it is of any value to anyone else. Not unlike programming, just because something is working when you write it, doesn’t make it of value to anyone else. Unfortunately, that mess of notes you took 3 years ago, is probably of little value now, even to you. The realistic truth, is that you then, is not you now. This is just like bad code. Trust me, I know because I’ve written so much bad code it’s mind boggling.

It’s not like this wasn’t a problem with writing. That’s why people invented literary tools, sentence structure, paragraphs. That’s why we have archetypes, and plot patterns. It’s to better communicate our stories. These things exist in programming, we have numerous languages, different patterns and practices. Hell, we even have smells. All these things try and make our code more easy to understand, for others, and for ourselves.

Let’s go back to Separating of Concerns, and how any of what I just wrote actually applies to programming. If we stick with the metaphor, that coding is a lot like writing, then what in writing is “Separation of Concerns”? Well, in your travels I’m going to assume you’ve read a book. In that book might’ve been a Table of Contents, that Table of Contents laid out the chapters of the book. The ‘Logical Separations” in the book. The book is structured in such a way, that the chapters flow. The author has taken the time to logically bundle pieces of relevant information. Can you imagine reading a book that is teaching you about Botany, and in Chapter 1 they dive directly into the root structure of a Hibiscus, and on the next page the configuration of soil nutrients? That’s not a book I want to read. So the act of bundling relevant information, for consumption of the reader, is in fact “Separation of Concerns”. Now, you can take this further. Do you think that when the author is crafting her book, that she’s worried about what type of paper it’s going to be printed on, or the font size? Probably not. Though — if she’s writing a book that contains needs special paper and tiny font,  likely she will ensure that the printing process will indeed support her special paper and tiny font. She certainly isn’t going to worry about this while she’s writing the book. In this regard, the author is Separating Concerns, regarding her functional requirements i.e. writing the book, and the non-functional requirements that the book needs to be on special paper in tiny font.

If we consult Wikipedia in regards to “Separation of Concerns”, we can look at the statement from Edward Dijkstra, that probably coined the term.

Let me try to explain to you, what to my taste is characteristic for all intelligent thinking. It is, that one is willing to study in depth an aspect of one’s subject matter in isolation for the sake of its own consistency, all the time knowing that one is occupying oneself only with one of the aspects. We know that a program must be correct and we can study it from that viewpoint only; we also know that it should be efficient and we can study its efficiency on another day, so to speak. In another mood we may ask ourselves whether, and if so: why, the program is desirable. But nothing is gained —on the contrary!— by tackling these various aspects simultaneously. It is what I sometimes have called “the separation of concerns”, which, even if not perfectly possible, is yet the only available technique for effective ordering of one’s thoughts, that I know of. This is what I mean by “focusing one’s attention upon some aspect”: it does not mean ignoring the other aspects, it is just doing justice to the fact that from this aspect’s point of view, the other is irrelevant. It is being one- and multiple-track minded simultaneously.

The first time I read this quote, I don’t think I fully groked it. So I read it again. And again. And again. Then I remembered a term that a lot of developers will preach. Make it work. Make it good. Make it fast. Coined by Kent Beck, in the UnixWay we’ll go with sometime ago. But Dijkstra beat him to it. Kind of. The common theme here, is that these pieces are logically separated. You concern yourself with the correctness, the efficiency, and the functionality of your application each in isolation. All the while, keeping in the back of your mind the other concerns. It was eye opening.

Alright — enough philosophy. How does that actually affect my programming?

Well we know now, that Separation of Concerns is essentially grouping logically functions of our program. That allows us to worry about a certain function of our application, without flooding our minds with other pieces. It allows you to focus. I don’t care how smart you think you are, you can’t focus on more than one thing at a time. If you try when you’re programming, you’ll end up with a tangled mess. You’ll start to bring pieces that belong in other areas, into the area you are. Then you’ll take pieces from where you are, and put them in areas they don’t belong. The smartest people, have the innate ability to focus on one thing at a time, while keeping track of all the other things outside.

While authors have chapters. As programmers we have abstractions. In my opinion, the two definitions that most closely apply to programming are:

the process of considering something independently of its associations, attributes, or concrete accompaniments.

and

the quality of dealing with ideas rather than events.

The first part of an abstraction, is that it lets you consider the component devoid of its baggage. You don’t care that it references EntityFramework, Boost 1.61, or the entirety of  GitHub. You don’t care that it has 1.3 million member variables, and 42 private functions. The only thing you care about is that it fulfills its contract to you. That is, you care about it’s public API. You ask for a list of Foo, you better get a list of Foo. That’s why you need to keep your public API clean and concise. Because that’s your first layer of abstraction.

The second definition, and an extremely important part of an abstraction. Is that it allows you do deal with a concept, rather than its details. This lets you think at a higher level, and deal with larger concepts without drowning in all the details. The (not so) modern remote or clicker on a television, had an abstraction that allowed you to press “up”, and that would tune the frequency of the television to the channel. This allowed you to work with the idea of “up” and “down” on your remote, to tune your television. Instead of being concerned with the tuning of the radio frequency that represents the channel.

Obviously given the fact that this entire post is riddled with metaphors, you might already know I’m a sucker for metaphors. The good news is, I’m about ready to unveil the pièce de résistance, of my metaphors. It’s the one I think most clearly buttons this concept up. It’s the car. The car, isn’t just a fantastic example when we’re teaching inheritance. It’s just a great all around metaphor when it comes to programming.

Specifically the steering wheel — this is a fantastic abstraction metaphor. You get into your car, and you look at the wheel. Do you care about the mechanics behind it? No. Do you care about the linkages between the wheels and whatever makes them turn? Nope. How about the power steering pump? The electronics? Nope, and Nope. You care that this thing makes your vehicle go left and right.

Do you know why this is so important when it comes to driving? It’s because driving is complicated, you need to have quick reaction times, and be able to focus on other things, like the rules of the road. At that level, you only have the capacity to concern yourself with “left” and “right” when it comes to steering. Imagine what driving would be like, if you had to push and pull leavers and rotate gears to turn. It would be a nightmare. That wheel in the cockpit of your vehicle, allows you to focus on actually driving, instead of the details of turning the wheels. It moves that concern to a different area. Now, do the mechanics behind that wheel still matter — hell yeah! But as long as they’re functioning when you’re driving, it isn’t your concern. It’s beautiful. The second benefit of this, you can drive a bunch of different cars. You could have a beat up pinto today, and tomorrow be “rolling ‘benz”, all because you know how to use a steering wheel. Steering stays the same, and it has for many years.

Another awesome benefit of the steering wheel, debug-ability. Say you crash your pinto taking a turn. Pretty easy to figure out where the bug is. Is the bug between the seat and the wheel, or the wheel and the head lights? Let’s check, when I turn left, do the wheels turn left? Yes. Is it the correct amount? Check. Okay — problem lies between the wheel and the seat. Easy.  It’s also really easy to check this when the car comes off the lot, or after you’ve had it serviced. Weird — that sounds a lot like unit testing to me.

So in order to sum all of this up. Separation of Concerns affects the entire spectrum of software development, from architectural design, right down to the details of the code. It’s about organization, and only concerning yourself with one topic at a time, all the while keeping in mind those other pieces. You first concern yourself with the design of your program. Capture the like ideas, divide them into chapters. While you’re implementing your chapters, look for steering wheels. Let your chapters flow into one another, but don’t mix Chapter 1 and Chapter 13.  Find spots for steering wheels, don’t force them to use gears and knobs. Mostly — know that this is a process, and it’s hard. You’re likely not going to get it right the first time. It’s just about trying, keeping these concepts in the back of your mind, and looking for opportunities to apply them.

I hope that this post has brought some light to the topic of Separation of Concerns. Maybe next time I’ll try my hand on one of the other concepts of Computing that I got wrong so many times.

“Organizing is what you do, before you do something, so that when you do it, it is not all mixed up” — A.A. Milne

I hope you have a splendid day, and as always — Happy Coding!

PL

 

 

Separation of Concerns

Make it work, Make it Right, Make it Fast

The Zero Cost Abstraction of Iteration

I’ve been hooked on C++ for about 10 years now. Since CMPUT101, I’ve been attracted to the syntax of the language, the simplicity of use, and later the driving ideals behind the language. C++’s author Bjarne Stroustrup, stands alone when it comes to preaching language ideals and pushing the language forward all while respecting these ideals. This is no easy task, especially when the language is designed by a committee. I’ve always been convinced one of the key reasons C++ is such a large success, and has remained so timeless; is the fundamental guiding principles behind the language. The principle that I believe reigns supreme is the ‘Zero Cost Abstraction’.

What is the ‘Zero Cost Abstraction’? Also called a ‘Zero Overhead Abstraction’. Well — it’s an abstraction, that costs nothing. Not like monetary currency; or a favour. Instead resource or runtime cost. Bjarne’s definition is “an abstraction that imposes no space or time overhead in excess of  what would be imposed by careful hand coding of a particular example of the abstraction.” So in other words, an abstraction that doesn’t use any more resources than if you carefully crafted the assembly yourself.

Well then, what is an ‘abstraction’? Well an abstraction is a concept that you can work with, that ignores the details of operation. A good metaphor for this is a steering wheel on a car. You turn the wheel left and right, to turn left and right, but you’re not concerned with the details of actually moving the wheels of the car on the road. In fact, you don’t want to be concerned with those details at the level of driving.  You want to be more focused on the bigger task at hand — driving the car.

So abstractions in computing allow us to work with concepts, craft algorithms and structure code, so that we don’t have to worry about the details. Programming languages themselves are abstractions, they allow us to work with logical operations, classes, English words, and common symbols to create instructions that cause computer hardware to do things. Languages like C and C++, are considered ‘close to the metal’, this means that they only thinly abstract the assembly that is run on the processor, only thinly abstract the management of memory (either directly to the MMU or through the OS), and only thinly abstract the other pieces of hardware. Languages like C# and JAVA (shudder), are higher level languages, meaning they have many layers between the code and the actual instructions that execute on the CPU. These higher level abstractions give way for more flexibility, but often have a cost. In the case of JAVA, the flexibility of portability, at the cost of run-time and space overhead. Garbage collection adds the flexibility of not having to worry about memory management, at the cost of run-time, and space overhead. Not to mention the cost to developers, as the become brainless in the areas of memory lifetime, and ownership rules.

[Coming Soon – a post on Virtual Machines]

So what does any of this have to do with the ‘Zero Overhead Abstraction’ principle? Well, obviously I have a story to go along with it. So some time ago I was working on my library [ASPeKT] and I was soliciting the help of the internet for advice on how to work better with the IL I was crafting. The comments I got, were, well, unexpected to say the least. The majority of the criticism I received was my use of direct for loops for iteration. As opposed to the cooler C# foreach loop or even better LINQ-to-everything!! Now, I can take critiquing of my code, after all that’s how you learn. So I pondered this for quite some time. I reviewed some of the pull requests which had transformed some of my boring for-loops, into beautifully crafted LINQ queries. I wasn’t buying it. I just couldn’t. It hid some of the intent of what I was trying to do, and call me old school, but I found it harder to read.

Enter foreach, this one I liked. C++11 introduced new semantics for it and I liked the clarity that it gave. When you’re iterating a collection using an indexer, the first thing you do is get the item at the index. The foreach, just abstracts this and your boundary checking in a nice syntax package. Color me smitten. Now, I didn’t actually refactor much in my library to use foreach. Honestly, I like it but I wrote the code already and it worked. However I started using foreach, pretty much everywhere I could, just like I did in C++ now. I know that C# probably had this before, and I obviously adopted it backwards, but I do a lot of shit backwards. So sue me. 

Fast forward a couple of months, I’m reading “Writing High-Performance .NET Code” by Ben Watson. He’s got a little section on loops for iteration. The section I think was on comparing C++ to C# for performance. When we’re talking speed of execution, less instructions is more. The less instructions you have to run, the faster your program will be. The fastest program you can write, is one that does nothing.

There was a snip on comparing a loop in C# to a loop in C++, and the generated ASM instructions. He was making the statement that C# doesn’t ALWAYS have much overhead over a language like C++. He showed how old skool for loop iteration, was virtually the same instructions for C++ and C#. But the foreach, it was something else. I was floored, I had never really thought about it, but at that moment I did. What does a foreach in C# actually do?

His example was something like this

[C++]
int sum2()
{
    int range[4] = { 1, 2 , 3 , 4};
    int sum=0;
    for(auto i=range; i<range+4; ++i)
    {
        sum+=*i;
    }
    return sum;
}

[ASM]
//-O2 Disabled so it wouldn't optimize the loop out
sum2(): # @sum2()
  push rbp
  mov rbp, rsp
  lea rax, [rbp - 16]
  mov rcx, qword ptr [.L_ZZ4sumvE5range]
  mov qword ptr [rbp - 16], rcx
  mov rcx, qword ptr [.L_ZZ4sumvE5range+8]
  mov qword ptr [rbp - 8], rcx
  mov dword ptr [rbp - 20], 0
  mov qword ptr [rbp - 32], rax
.LBB1_1: # =>This Inner Loop Header: Depth=1
  lea rax, [rbp - 16]
  mov rcx, qword ptr [rbp - 32]
  add rax, 16
  cmp rcx, rax
  jae .LBB1_4
  mov rax, qword ptr [rbp - 32]
  mov ecx, dword ptr [rax]
  add ecx, dword ptr [rbp - 20]
  mov dword ptr [rbp - 20], ecx
  mov rax, qword ptr [rbp - 32]
  add rax, 4
  mov qword ptr [rbp - 32], rax
  jmp .LBB1_1
.LBB1_4:
  mov eax, dword ptr [rbp - 20]
  pop rbp
  ret
.L_ZZ3sumvE5range:
  .long 1 # 0x1
  .long 2 # 0x2
  .long 3 # 0x3
  .long 4 # 0x4
[C#]
static class Program
{
     static int sum()
    {
          int[] range = new int[]{ 1, 2 , 3 , 4};
          int sum=0;
          for(var i=0; i<4; ++i)
          {
                 sum+=range[i];
           }
          return sum;
   }

}

[JIT ASM]
Program.sum()
    L0000: push ebp
    L0001: mov ebp, esp
    L0003: push edi
    L0004: push esi
    L0005: mov ecx, 0x717168e2
    L000a: mov edx, 0x4
    L000f: call 0x58f3200
    L0014: lea edi, [eax+0x8]
    L0017: mov esi, 0x251c084c
    L001c: movq xmm0, [esi]
    L0020: movq [edi], xmm0
    L0024: movq xmm0, [esi+0x8]
    L0029: movq [edi+0x8], xmm0
    L002e: xor esi, esi
    L0030: xor edx, edx
    L0032: mov ecx, [eax+0x4]
    L0035: cmp edx, ecx
    L0037: jae L0049
    L0039: add esi, [eax+edx*4+0x8]
    L003d: inc edx
    L003e: cmp edx, 0x4
    L0041: jl L0035
    L0043: mov eax, esi
    L0045: pop esi
    L0046: pop edi
    L0047: pop ebp
    L0048: ret
    L0049: call 0x73a52b10
    L004e: int3

As you can see 25 instructions in C++ vs.  30 instructions for C#. So your standard for loop in C++ and C# are running essentially the same instructions.

The foreach was a different story — he wouldn’t even show the instructions. He only showed the generated IL, and let me tell you, it was a lot.

In my own research, the ASM generator that I used, generated 150+ instructions, which didn’t seem like a lot. However, I did notice is that it didn’t generate ASM for the actually calls to MoveNext(), it just used the syntax ‘call’ MoveNext(). Which likely has a lot more instructions under the hood.

Let’s compare that to the pure C++, range foreach.

[C++]
int sum()
{
    int range[4] = { 1, 2 , 3 , 4};
    int sum=0;
    for(auto i : range)
    {
        sum+=i;
    }
    return sum;
}

[ASM]
sum(): # @sum()
  push rbp
  mov rbp, rsp
  mov rax, qword ptr [.L_ZZ3sumvE5range]
  mov qword ptr [rbp - 16], rax
  mov rax, qword ptr [.L_ZZ3sumvE5range+8]
  mov qword ptr [rbp - 8], rax
  mov dword ptr [rbp - 20], 0
  lea rax, [rbp - 16]
  mov qword ptr [rbp - 32], rax
  mov rax, qword ptr [rbp - 32]
  mov qword ptr [rbp - 40], rax
  mov rax, qword ptr [rbp - 32]
  add rax, 16
  mov qword ptr [rbp - 48], rax
.LBB0_1: # =>This Inner Loop Header: Depth=1
  mov rax, qword ptr [rbp - 40]
  cmp rax, qword ptr [rbp - 48]
  je .LBB0_4
  mov rax, qword ptr [rbp - 40]
  mov ecx, dword ptr [rax]
  mov dword ptr [rbp - 52], ecx
  mov ecx, dword ptr [rbp - 52]
  add ecx, dword ptr [rbp - 20]
  mov dword ptr [rbp - 20], ecx
  mov rax, qword ptr [rbp - 40]
  add rax, 4
  mov qword ptr [rbp - 40], rax
  jmp .LBB0_1
.LBB0_4:
  mov eax, dword ptr [rbp - 20]
  pop rbp
  ret

Hmmm…. 30 instructions. So as you can see, this is an illustration of a ‘Zero Cost Abstraction’. The code has been shrunk by quite a few characters. It becomes easier to read and reads with more intent, yet it doesn’t carry any overhead over the original loop.

So, what’s the development cost of writing your own foreach enumerable collection in C#. Implementing the IEnumerable concept.

Well — first you need to implement the IEnumerable interface, which returns an IEnumerator. The IEnumerator class is really the meat and potatoes. It contains your iteration state and a reference to your collection. You need to implement the MoveNext() call to increment the enumerator, which returns true or false based on whether it incremented. Then you need to implement Reset(), which resets the enumerator. You need to implement the ‘Current’ field to return the current object.

Vs.

What’s the development cost of making something enumerable in C++. Implementing the iterator concept.

You need to implement the iterator concept. Iterator concepts are described here, the minimum you need is the ForwardIterator. Which you need to be able to read and increment with multiple passes. The iterator concept models the pointer, so you need to implement operator++() and operator*(), and operator==(). Like the IEnumerator the iterator is the brains of iterator (fancy that), and contains some reference to the collection as well as iteration state.

In order for your collection to work with C++ foreach, you need to implement a begin() and end() method, which return an iterator.

begin() => returns an iterator to the first object
end() => returns an iterator of one past the last object

It’s as easy as that.

The moral of this story, just because an abstraction makes the code cleaner, doesn’t mean you’re not paying for it, someway. Of course, the flip-side is, if there is careful thought put into the abstraction — you can eat your cake and have it too.

“Small leaks sink big ships” – Benjamin Franklin

Happy Coding!

PL

Ye Olde Double Dispatch; The Invasive Visitor Pattern; and Pattern Matching.

As the title suggests we’re exploring The Ol’ Double Dispatch, Visitor Pattern and Pattern Matching. Given this topic can be language agnostic, I’ll choose C++ for examples. We all know it’s the language of languages. Kind of like Latin. It also gives me a good framework to work with because it’s close to the metal, which hopefully makes things less complicated, and way better than JAVA because, well… JAVA. Need I say more?

I’ll get to the back story, and an architecture choice which leads to a pervasive (invasive) design pattern, but first I’ll start with some history. Practitioners of C, would remember the paradigm of separating function from data, they remember this; because they have no other choice. In C, your tools are functions and structs, so that’s really all you got. Along the way some clever individuals invented something called virtual function dispatching. This allows you to have different function implementations based on the different type of data. This is a little something we like to call ‘polymorphism’ in the Computing world, you’ve probably heard of it. In fact, polymorphism is a fundamental pillar of Object Oriented programming. It is also, a form of what is called ‘single dispatch’.  Whereby you make a single function call and it’s dispatched to the proper implementation based on the data type.

By this point, you’re probably saying “You said you’d talk C++, but now you’re talking about C.” Well it’s important because it illustrates my point, and what would we be without C? Some type of cave person punching holes in cards? Give your head a shake. Anyways, the C++ compiler builds a virtual function table, and ensures that the correct function is called based on the type, all with the nice syntax of C++ to write it. So this example will be C++ syntax, to show virtual single dispatch.

// create a virtual base class
class base
{
public:
    virtual ~base() = default;
    virtual void do_something()
    {
        // do something
    }
};

// override the base class
class derived : public base
{
public:
   virtual void do_something() override
   {
       // do something derived
   }
}; 

int main()
{
     base b;
     derived d;
     base &a = b;
     base &c = d;
     
     // call the correct function, from the base, to the derived
     // base do_something
     a.do_something();

     // derived do_somethng
     c.do_something();
}

So Single Dispatch, virtual function table, and data / function segregation.

Now, there’s a second type of Single Dispatch, but it doesn’t exist in C (the latest C has it apparently), it’s called ‘function overloading’. In C++,  it’s done at compile time. Basically, the compiler picks the right function based on the type passed in. You know.. this.

void foo(int i)
{
    // do foo for int
}

void foo(double d)
{
    // do foo for double
}

int main()
{
   double pi{3.1415};
   int i{0};
   foo(i);
   foo(pi);
}

As I mentioned, this form of dispatching is only at compile time. The compiler has to know the type when selecting the proper overload. So something like this, won’t work.

class ibase
{
public:
    virtual ~ibase() = default;
    virtual void do_something() const = 0;
};

class derived1 : public ibase
{
public:
   virtual void do_something() const override
   {
   };
};

class derived2 : public ibase
{
public:
   virtual void do_something() const override
   {
   }
};

void foo(const derived1 &d)
{
    d.do_something();
}

void foo(const derived2 &d)
{
   d.do_something();
}


int main()
{
   // This won't compile, it's for illustration purpose
   derived1 d1;
   derived2 d2;
   ibase &b1 = d1;
   ibase &b2 = d2;
   foo(b1);
   foo(b2);
}

Now, I know what you’re thinking — ‘There’s no reason why you would ever do this. Just use polymorphism to solve this.’ You’re right! For this example.

However, the point is, that if you combine the two examples, you get ‘Double Dispatch’.  Now, if C++ supported this, that would be grand. But it doesn’t, and the problem lies with what’s illustrated above. You can’t use a runtime type to do function overloading.

From this point forward, we’re going to use a image system as an example. In our image system, the image can be of different types, and we want to be able to apply some different action to the image; adjust colour, crop, scale, black & white, etc. If we sketch our example in our fairytale C++ language that supports runtime type function overloading. It would look like this.

struct rgb
{
public:
  unsigned char red, green, blue;
};

class iimage
{
public:
    virtual ~iimage()  = default;
    virtual int height() = 0;
    virtual int width() = 0;
    virtual rgb get_pixel_color(int x, int y) = 0;
    virtual void set_pixel_color(int x, int y, rgb color) = 0;
};

class bmp_image : iimage
{
  // any none shared functions  & data
  // implement shared functions
};

class jpg_image : iimage
{
  // any none shared functions & data
  // implement shared functions
};

class iaction
{
public:
    virtual ~iaction() = default;
    virtual void apply(bmp_image &image) = 0;
    virtual void apply(jpg_image &image) = 0;
};

class adjust_color_action : iaction
{
    virtual void apply(bmp_image &image) override
    {
       // some specific algorithm for bmp images
    }
    
    virtual void apply(jpg_image &image) override
    {
       // some specific algorithm for jpg images
    }
};

void apply_action(iimage &image, iaction &action)
{
    action.apply(image);
};

int main()
{
    iimage &image = generate_image();
    iaction &action = get_user_action();
    apply_action(image, action);
}

So as you can see, if this was to compile, we’ve done two things, we’ve separated our algorithms from our data; actions & images, and given ourselves the ability to apply different algorithms based on the different types of data. We’re using both types of single dispatch at once, a runtime polymorphic virtual function dispatch, when we call ‘apply’. Then a runtime function overload, with the argument passed in. That right there — is Double Dispatch.

Unfortunately for us. That runtime function overload, doesn’t exist in C++. So we need to somehow invert our call, so that the compiler can be sure of the type when it compiles.

Enter Visitor Pattern.

By inverting the dispatch of the action, onto the image base, we can cause the dynamic dispatch to the action, while knowing at compile time the type getting passed in. It looks like this.

struct rgb
{
public:
 unsigned char red, green, blue;
};

class iaction;

class iimage
{
public:
 virtual ~iimage() = default;
 virtual int height() = 0;
 virtual int width() = 0;
 virtual rgb get_pixel_color(int x, int y) = 0;
 virtual void set_pixel_color(int x, int y, rgb color) = 0;
 virtual void apply(iaction &action) = 0;
};

class bmp_image;
class jpg_image;

class iaction 
{ 
public: 
    virtual ~iaction() = default; 
    virtual void visit(bmp_image &image) = 0; 
    virtual void visit(jpg_image &image) = 0; 
};
class bmp_image : iimage
{
    // any none shared functions & data
    // implement shared functions
    virtual void apply(iaction &action) override
    {
         // the *this, tells the compiler, that when you
         // call apply on the bmp_image, it will call the
         // bmp_image overload of the iaction
         action.visit(*this);
    }
};

class jpg_image : iimage
{
    // any none shared functions & data
    // implement shared functions
    virtual void apply(iaction &action) override
    {
        action.visit(*this);
    }
};

class adjust_color_action : iaction
{
  virtual void visit(bmp_image &image) override
  {
    // some specific algorithm for bmp images
  }
 
  virtual void visit(jpg_image &image) override
  {
   // some specific algorithm for jpg images
  }
};

void apply_action(iimage &image, iaction &action)
{
    image.apply(action);
};

int main()
{
   iimage &image = generate_image();
   iaction &action = get_user_action();
   apply_action(image, action);
}

Okay — so as you can see, in this example we’re emulating Double Dispatch, by inverting our calls. Which uses first polymorphism to make the correct call, and then a compile time overloaded function. Voila! Double Dispatch, kind of. This pattern lends itself very nicely when you need to separate your function, from your data. It allows you to easily expand data function, without having to change code in the data. However, additional data becomes a bit of a pain, because you need to change all of your function classes to support the new data class.

Now, I mentioned earlier that there is an architecture that the Visitor Pattern becomes quite pervasive, to a point of being almost invasive. It’s the dreaded ‘Anemic Domain Model’ architecture / pattern! Gasp! What is the ‘Anemic Domain Model’? Well according to Wikipedia, it is “Anemic domain model is the use of a software domain model where the domain objects contain little or no business logic (validations, calculations, business rules etc.).”

[ See Post In Defense of The Anemic Data Model ]

If you’ve architected your system in this way. You might start to see where the visitor pattern starts to become pervasive. Just because you chose to decouple function from data, doesn’t mean you throw OO out the window completely. Right? The issue you face, is that if a component in your data model wants to become a hierarchy, how do you deal with it? You can’t add function to the data. Because that’s the point of your model. You need a pattern where you can apply a dynamic algorithm, to a dynamic piece of data.

Enter Visitor Pattern.

Because RESTful APIs lend themselves nicely to this pattern, let’s reimagine our image processing example as a REST api.

Let’s say we want to PUT to a transform, in our image collection. We want to be able to 1) have multiple transforms, and accept different kinds of images.

Our API is

PUT api/images/transform
{
   "action":"adjust_color",
   "image":"bin_data"
}

Now, imagine we had some kind of mechanism, that would dispatch us the deserialization of our JSON blob to

void on_put_images_tranform(iimage &image, iaction &action);

You could design things differently, where you didn’t need the visitor pattern. Although, I think this is a nice blend of OO, patterns, and separation of concerns. So it nicely illustrates my point.

HOWEVER! The visitor pattern isn’t cheap, you need multiple classes, you need multiple interfaces and it does obfuscate data away from function.

Enter “Pattern Matching”.

What is Pattern Matching, you’re asking? How does it relate to the Visitor Pattern? Pattern matching, in regards to programming languages, is for all intents and purposes a switch statement on steroids.

Your average switch looks like this:

enum states { stopped, running, error };

std::string to_string(states s)
{
    switch(s)
    {
    case states::stopped:
         return "stopped";
    case states::running:
         return "running";
    case states::error:
         return "error";
    default:
         return "unknown";
    } 
};

Imagine this guy, if you could apply that to types.

I need to switch languages here. C++ has a library, called Mach7 which is a pattern matching library, and it allows for functionality similar to what I’m going to describe. I just find that the C# syntax is cleaner and easier to read. As of C# 7 pattern matching, and the ability switch on object type, is a thing. The first time I saw it, I thought ‘Honestly, who would ever use that??’ Apparently, me.

I’m going to reimagine our example, in a hybrid language. Because I want to use the C# pattern matching syntax, but I want to stick with the original C++ example.

Instead of needing to perform the inversion, we can use a runtime detection of type to dispatch to the right call.

Like so

void apply_action(iimage &image, iaction &action)
{
    switch(image)
    { 
    case bmp_image bmp:
         action.apply(bmp);
    case jpeg_image jpg:
         action.apply(jpg);
    default:
       throw unsupported_object_exception();
    }
}

int main() 
{ 
    iimage &image = generate_image(); 
    iaction &action = get_user_action(); 
    apply_action(image, action); 
}

As you can see, we’re very close to the initial Double Dispatch described at the start of the post. We’ve come full circle!

To recap, Double Dispatch is a form of multiple dispatch, allowing us to dispatch polymorphic function on polymorphic data. The Visitor Pattern, is a pattern that allows us to emulate Double Dispatch in languages that have no support for it. The Visitor Pattern is especially good at allowing us to separate function from our data. It becomes very pervasive in a pattern where we keep our data and logic separate (an anti-pattern), but want to have data hierarchies. Pattern Matching is a language construct that allows us use a switch statement on steroids, to switch on object type. Giving us almost Double Dispatch.

Happy Coding!

“The ultimate dream in life is to do what you love, and learn something from it” – Jennifer Love Hewitt

References

Virtual Functions in C [https://www.embedded.com/electronics-blogs/programming-pointers/4391967/Virtual-functions-in-C]

Double Dispatch with an Inverted Visitor Pattern [http://www.drdobbs.com/double-dispatch-with-an-inverted-visitor/184403497]

In Defense of The Anemic Data Model

According to Martin Fowler, who coined the term, this pattern is an ‘Anti-Pattern’, and it’s “contrary to the basic idea of Object Oriented design”. I’m not an Engineer (although I’m sure my parents wish I was), but engineering is about picking the best approach to solve the problem. The fact of the matter is, depending on the problem at hand, sometimes an ‘Anti-Pattern’ fits. This particular one, actually does serve some purpose, and I think the benefits outweigh the costs. So come with me for a moment, as I defend this pattern.

Firstly, a major argument against this architecture is that it “violates encapsulation”. It depends on your definition of the word ‘encapsulation’. If we refer to Wikipedia, we get two different definitions:

  • A language mechanism for restricting direct access to some of the object‘s components.[3][4]
  • A language construct that facilitates the bundling of data with the methods (or other functions) operating on that data.[5][6]

Some see the concept as either or, some see it as both. The reality is I could argue either. In fact, to me (and I borrowed this from Uncle Bob’s Clean Architecture) C has a very good mechanism for 1) bundling data and function 2) hiding direct access to functions of the object. That mechanism is the header / definition file pair. You expose everything you want the client to see via the header, and keep anything private in the compiled definition. Languages like C# and JAVA (shudder), expose ALL the functionality in one file, exposing to the client ALL the implementation details of the class. Isn’t that a violation of ‘encapsulation’? To me, having a class that stores data, and a class that stores function, then having a module that exposes them together. Is in fact, better encapsulation.

Another massive benefit of this pattern, is the ‘Separation of Concerns’. If you’re keeping all logic within a class, say you want to keep business logic, persistence logic, and presentation logic in the same class. You’ve now just created a coupling between your storage, your business logic, and your presentation layer. Trust me when I tell you, I’ve been to this Hell, and it isn’t a picnic. It’s an unmaintainable nightmare, the kind that Freddy himself couldn’t engineer. You can fight to use language features like partial classes to manage the distinction, but it only helps a little. You might argue that the idea is to only keep business logic with the class. Separate all else. Well what happens when the line between presentation and business logic become fuzzy? Well, people start coupling, and down the rabbit hole we go. This is illustrated in this statement by Fowler himself “The logic that should be in a domain object is domain logic – validations, calculations, business rules – whatever you like to call it. (There are cases when you make an argument for putting data source or presentation logic in a domain object, but that’s orthogonal to my view of anemia.)” [1] It isn’t orthogonal, in fact, it is the problem. You might be able to make the argument, but someone else might not. So now, you’ve got someone with a little less experience, and a little less insight, who sees this and replicates it, for the problem they’re solving. Next thing you know, you’re wondering how your UI layer now needs your Database layer to compile. Oh! What about code reviews, and proper discipline. We ALL know how software development works, you’ll spend hours in review, debating why this little piece of persistence logic fits, then why this little piece of UI logic fits. If you follow a clear cut pattern, don’t mix your logic with your data, you don’t have this issue, and it’s easier to catch in a code review, because there isn’t room for debate.

You can implement a very nice service layer, which works on your data model, AND use OO techniques. It is possible.

This pattern, keeping your data separate from your logic, finds massive benefit when you’re working with things like RESTful APIs or really any form of serialization / deserialization to POD data streams. This is due to the fact that serialization of function is difficult at best. Rehydration of complex type hierarchies isn’t child’s play, and doesn’t lend itself nicely to simple interfaces (see ODATA as an example). So you want the objects you pass back and forth to be light and airy. These objects are often referred to as DTO’s or ‘Data Transfer Objects’. In this pattern, you pass them between services, that can persist the object, do logic on the object, or display the object. You might decorate them to add functionality, but at the core, the object stands as data alone.

I’m not saying this ‘Anti-Pattern’ is a silver bullet, because the only silver bullet I believe in is Coors Light. I am however saying, if you’re running into the trap of a coupled nightmare, where one too many people made the argument that presentation and data source logic should be in your model, you might want to see if this architecture helps.

Happy Coding!

“There is nothing either good or bad but thinking makes it so.” – William Shakespeare

The Adventures of Dependency Injection and Inversion of Control.

I like to think my first words were ‘std::cout << “Hello World” << std::endl;’. The canonical C++ Hello World program. But alas, they weren’t. I cut my teeth on QBasic (Quick Beginners All purpose Symbolic Instruction Code, not to be confused with QuickBASIC). I did my time in QBasic, writing ‘viruses’ that would show download progress bars, and print ‘Ha Ha’ infinitely (sorry Dan).

Oh look, I’ve digressed; Back on topic — My first C++ experience was in CMPUT101. That’s when I fell in-love with the language. It was the :: that did it. Also, I always liked the simplicity of the language (Say what?). Anyways, as a young (and full of vigor, I might add) C++ software developer fresh out of school, I often found my code tangled and tightly coupled. Class design in C++ is hard. For me, often my class designs consisted of a lot of value members, and a lot of  concerns fused together.

A value member, is a instance of a class (or POD) as a member variable, of another class. In C++, value members are laid out in memory as they’re declared in the class.

class foo
{
public:
   int A;
   int B;
};

class bar
{
public:
   foo fooA;
   foo fooB;
};

If sizeof(int) == 4, then sizeof(foo) == 8 and sizeof(bar) == 16; Hopefully this makes sense.

[I’m getting there!]

So the thing about value members and call by value in C++, is that there is no polymorphism. You only get polymorphism, or virtual function calls, when you call on a reference or a pointer. Which means, when your class is full of value members, you’re EXTREMELY tightly coupled to the implementation of those members.

Here’s an example to illustrate what I’m talking about.

class file_to_database
{
private:
    file file_;
    database database_;
public:
    file_to_database(const std::string &filename, 
                    const std::string &connect_s)
    {
    }

    void parse()
    {
         std::string line;
         while(file_.read_line(line))
         {
              std::string tablename;
              std::string v1, v2;
              // do some parse work
              database_.insert(tablename, v1, v2);
         }
    }
};

int main(int argc, const char** argv)
{
    file_to_database ftdb(argv[0], argv[1]);
    ftdb.parse();
}

As you can see. We’re very very coupled to both the implementation of the file and database.

When you start delivering code for realz, and have to debug in the field. That’s about the time you remember back to school, and this thing called a ‘Unit Test’. Then it dawns on you, *that might not have just been a ploy to get me to do more homework, but actually useful!!!* So you think to yourself, *Self — I should probably unit test my code*. So you trudge down that road. Hi! Ho! Hi! Ho!

There’s only one problem with that. Everything in your class is a value member. Meaning no polymorphism. Meaning you’re stuck with the implementation you wrote, coupled to a database and all. *Shit.*

I headed on a path of discovery. I was going to solve this problem. How can I make my classes more testable and less coupled to implementation details?

If I boil down my research (and years of experience after). It comes down to 3 rules.

  1. Favour composition over inheritance – inheritance is the tightest coupling you can get. Unless you need it, don’t use it.
  2. Develop to an interface – use well designed interfaces to separate implementation from algorithms.
  3. Use Dependency Injection – dun. dun. dun.

Let’s see where I went wrong.

  1. Check. My classes were generally composed of other types, as value members.
  2. No polymorphism, no interfaces.
  3. What is this even??

Now, at this point I was part of the all mighty C++ development crew!! The language coursed through my veins. Oooh Rah. I had a major hate-on for Enterprise Developers and any type of managed languages. (I still hate JAVA, so if you’re a JAVA developer stop reading right now and go learn a real programming language. Just kidding! 🙂 No but seriously, my language compiles your language.) However, I had heard about this thing called ‘Dependency Injection’ from the Enterprise team at work. I also had read about it on the internet. I took a look at some ‘Dependency Injection’ code examples on the internet. Uhhh. Okay Mr.C-Sharp, where the heck does anything begin, who owns what? Wow. I’m going to stay as far from ‘Dependency Injection’ as I can.

By this time, I had solved my unit testing woes. I started using reference members to pure virtual classes (interfaces). Lastly I started taking all the implementations of the classes in my constructors. This allowed me to write tests against my classes, make sure they functioned correctly using mock implementations. Then in production, supply the real-world implementation. I could now mock out my databases and files, supply those in the constructor and test my classes. This also, really simplified my ownership models. I won. Check and mate, Mr. C-Sharp. No ‘Dependency Injection’ here.

  1. Check.
  2. Check.
  3. Hell no. Who needs that? I’ll control where things are created, destroyed and owned. Thank you very much.

It didn’t matter, because I was now cooking with dynamite, I could unit test! Hizuh! I don’t need your silly ‘Dependency Injection’ where I have no idea who made what, when or who owns anything.

Here’s the example above, re-imagined to suit my testing needs.

class ifile
{
public:
   virtual ~ifile() = default;
   virtual bool read_line(std::string &line)=0;
};

class idatabase
{
public:
   virtual ~idatabase() = default;
   virtual void insert(const std::string &tablename,
                       const std::string &value1,
                       const std::string &value2)=0;
};

class file_to_database
{
private:
     ifile &file_;
     idatabase &database_;
public:
     file_to_database(ifile &file, idatabase &database)
     :file_(file), database_(database)
     {
     }

     void parse()
     {
         std::string line;
         while(file_.read_line(line))
         {
              std::string tablename;
              std::string v1, v2;
              // do some parse work
              database_.insert(tablename, v1, v2);
         }
     }
};
class file : public ifile
{
public:
    file(const std::string &filename)
    {
    }
    virtual bool read_line(std::string &line) override
    {
        // implementation
    }
};

class database : public idatabase
{
public:
   database(const std::string &connect_s)
   {
   }
   virtual void insert(const std::string &tablename,
                       const std::string &value1,
                       const std::string &value2)
   {
        // implement
   }
};

int main(int argc, const char** argv)
{
    file f(argv[0]);
    database(argv[1]);

    file_to_database ftdb(file, database);
    ftdb.parse();
}

As you can see, this refactor takes the parsing code from near impossible to test without a file and a database. To extremely easy to test, by mocking out our inputs (ifile) and our outputs (idatabase). The awesome thing, I didn’t even touch the parsing algorithm. Just a couple smart interfaces, and introduce the dependencies in the constructor. Bingo. Bango.

So — a little while later, I’m attending CPPCON and I’m having a couple wobblies with a friend. He’s a C++ Guru and did some time at a C# shop. We got onto this topic. I tell him “Man, have you heard of this ‘Dependency Injection’ thing? What a nightmare. How do you even know when things are constructed? Who even owns what?”

He pauses. Then he delivers a mind-bottling statement. “Dependency Injection IS NOT Inversion of Control.” I said, “What?!?” He pauses again. “Dependency Injection IS NOT Inversion of Control. Dependency Injection is simple — just make your classes take what they depend on in the constructor…. When you use interfaces it makes it so you can replace the implementation of the dependencies, without modifying the class.” I think I almost fell off my stool (and it wasn’t the amount of wobblies I had). “No. No. No. Dependency Injection is this crazy-ass thing that obfuscates where objects get created and requires that everything on the planet be an interface, even simple things.” I cried.

He smiled, took a sip of his water — “You’re wrong. That’s an Inversion of Control container.” I take a sip of my beer. “Well. What’s an Inversion of Control container?”. He looked at me smugly, “What you just described. That is.”

It was this moment, when I learned the difference between ‘Dependency Injection’ and ‘Inversion of Control’. Dependency Injection is that simple, make your classes take their dependencies in the constructor. If those dependencies happen to be interfaces, you can swap out implementations as needed and your class won’t change. This is sometimes referred to as the ‘Hollywood Principle’ — Don’t call us. We’ll call you.

Inversion of Control, is succeeding control of object creation, and ownership to a framework. It utilizes ‘Dependency Injection’ in order to build up objects in a hierarchical fashion.  In my opinion, these were frameworks created because some developer had nothing better to do with his/her time. Enterprise developers, amirite!?! 😀 But in all seriousness, they really obfuscate ownership and creation. Which is my opinion are fundamental to software design. This is done in the name of modularity, so I understand. However, I’m not a fan. They do have their usage in large applications that need extremely customizable and modular foundations. Although, I’d argue these are few and far between.

Lastly, neither of these are to be confused with ‘Dependency Inversion’. Sometimes, people will confuse ‘Inversion of Control’ and ‘Dependency Injection’ and call it by some ugly step child name of ‘Dependency Inversion’. ‘Inversion of Control’, uses ‘Dependency Inversion’, so does ‘Dependency Injection’. Essentially, ‘Dependency Inversion’ is ensuring that your higher level components, don’t depend on your lower level components. The term though, is generally used to refer to architecture design, at the module level. By making both high and low level modules depend on a shared interface i.e. one caller and one implementer, the direct dependency is now ‘inverted’.

In summary, ‘Dependency Injection’ is the act of taking all class dependencies via the constructor. ‘Inversion of Control’ also called ‘Inversion of Sanity’, is the act of allowing a framework to control all of the important decisions of your program, and you pretending to control it via XML. ‘Dependency Inversion’ is neither of these, but an architectural pattern that helps to decouple modules within a system, by having high and low level components work through interfaces.

Happy Coding!

“Be yourself, because everyone else is already taken.” — Oscar Wilde

 

The Wedding Cake Architecture

First, let me start by stating that I’m not claiming to have invented this. Not even close. I ‘borrowed’ the idea, from “Uncle Bob”. Interestingly enough, I stumbled upon it (kinda), before I ever read about it. Here’s the story.

I had had my doubts about frameworks and ORMs like Entity Framework for some time. What struck me as odd was a lot of the examples show direct usage of the table classes (classes that represent directly the data in the tables) at the API or UI level. Now, I understand the need for this in a blog post or an example for simplicity. What ends up happening though, is this becomes the foundation for reality.  Then once you’ve exposed classes that directly represent your table structure to an API, be it REST or WCF, you’ve unintentionally (or intentionally) coupled your API or UI to the database.  This means that often if you want to make a change to your table structure or persistence medium, you better be willing to shell out the time to fix the broken API clients or UI.

Armed with that thought, I went out to create an architecture that didn’t have this problem. I was dead-set on architecting a solution that ensured decoupling of the database and the clients of the API layer. I was going to develop an API that had a fluent business interface, and ensured that the persistence happened behind the curtains of the API.

The original design principle was dead simple. ‘Keep the persistence out of the API’. So there was a Business Logic Layer (BLL) which exposed a consumable API and housed the business and translation logic. Then a Data Access Layer (DAL) which housed the logic of storing the table classes. Classic separation of concerns. Classic.

OriginalArch

I went about my business of implementation. Then next thing I know!? This architecture worked, it performed, it was unit testable (mostly) and it was easy to understand! HooRay! Kinda.

To exemplify what I mean, here’s a canonical example of a bank transaction.

// Exposed via BLL DLL
public enum EntryTypes { Debit, Credit }

public class Transaction
{
    public Guid Id { get; }
    public Guid Account { get; }
    public DateTimeOffset Time { get; }
    public EntryTypes Type { get; }
    public double Value { get; }
}

public interface ITransactionManager
{
    Transaction Deposit(Guid account, double value);
    Transaction Withdraw(Guid account, double value);
}

public class TransactionManager : ITransactionManager
{
    IPersistence Persistence { get; }

   public Transaction Deposit(Guid account, double value)
   {
       // create a new transaction
       var transaction = new Transaction();
    
       // ...
       // translate the transaction to a transaction entry
    
       var entry = new TransactionEntry();
       // ... copy the fields
    
       Persistence.CreateTransactionEntry(entry);
       return transaction;
    }

    public Transaction Withdraw(Guid account, double value)
    {
       var account = Persistence.ReadAccountEntry(account);
       if( account.Balance < value )
            throw new InsufficientFundsException();
       // create a new transaction
       var transaction = new Transaction();
       // ...
       // translate the transaction to a transaction entry
       var entry = new TransactionEntry();
       // ... copy the fields
       Persistence.CreateTransactionEntry(entry);
       return transaction;
     }
}

// Exposed via DAL DLL
[Table("Transactions")]
public class TransactionEntry
{
    public Guid Id { get; }
    public Guid Account { get; }
    public DateTimeOffset Time { get; }
    public EntryTypes Type { get; }
    public double Value { get; }
}

[Table("Accounts")]
public class AccountEntry
{
    public Guid Id { get; set; }
    public string Owner { get; set; }
    public double Balance { get; set; }
}

public interface IPersistence
{
    void CreateTransactionEntry(TransactionEntry entry);
    AccountEntry ReadAccount(Guid accountId);
}

public Database : IPersistence
{
    public void CreateTransactionEntry(TransactionEntry entry)
    {
        // Code to store the table entry into a database.
    }
    // ...
}

Now, this example is contrived and won’t compile in any language but it illustrates my point. You can see from the client API, there is no mention of persistence. This means that the clients of the API don’t need to deal in classes that directly represent your tables (or know about them). I’ve intentionally let the two classes have identical fields, because this is just the reality for now. It leaves us the ability to change it in the future. If we ever need to change a table data type, add a column or change where the values get stored.

But there’s a problem with this architecture, it’s subtle (at least it was for me, experienced people are probably screaming ‘YOU IDIOT’) but it’s there. The fact that the BLL even knows about the table classes is a problem. There are a few things wrong:

  1. I used Entity Framework in this example. So I’ve basically just enforced my business logic to use Entity Framework. This isn’t really a bad thing, Entity is widely used, supported by Microsoft and easy to use (IMO). However, if you ever wanted to depart from Entity Framework, you’re going to have a bad time.
  2. I’ve coupled the Business Logic to the table columns (yet again). In this example, if you ever wanted to have different storage implementations, they better represent the data the same way across the implementations (or build a translation shim).
  3. I broke the Single Responsibility Principle on my BLL. Translating objects from API objects to database objects isn’t Business Logic so it’s got no ‘business’ being there.

Now, the saving grace of this architecture is that I did one thing right. I kept those details, the persistence details, away from the clients of the API. So even if I had released the API and had clients consuming, I wouldn’t break clients fixing my mistake.

As the architecture began to grow this oversight became more apparent. Which is always the case. I started to realize that things like porting to a different storage medium, or changing ORMs would pose a huge undertaking.

Another problem, since the only downstream interface coming out of the BLL utilized the table classes, all my tests were directly coupled to the table entries. I had a huge problem.

At this point I had already started reading “Clean Architecture” by Robert ‘Uncle Bob’ Martin. I started to understand where I had gone wrong, and those three issues noted above started to become clear, and so did a solution — Clean Architecture. Like I said, I stumbled across this architecture. More like tripped, fell, and face planted right into it.

Uncle Bob talks about a 4 ringed solution. In the centre ring, we have ‘Entities’ these are your ‘Enterprise Business Rules’. In the next ring, you have ‘Use Cases’ these are your ‘Application Business Rules’. Next, ‘Interface Adapters’ are your controllers and presenters. Then finally, ‘Frameworks and Drivers’ the external interfaces. He talks about never letting an inside ring, know about things in an outside ring. Can you see now my blunder?

Okay — so what would the point of this blog post be, if I didn’t have a little perspective on that architecture? Otherwise, I could just say ‘go read the book’.  Disclaimer: I’m not knocking Uncle Bob. I see the value in his architecture, and he’s got many many more years on me.

I think it can be simplified… I gave it a KISS. My interpretation is the ‘Wedding Cake Architecture’ and it looks like this.

WeddingCakeArch

It’s very very very heavily influenced by the Clean Architecture. Except that I’ve shaved out a layer. I’ve also intentionally drawn the layers with differing thicknesses, this is to illustrate the weighted dispersal of the code. You’ll have less code in the Business Models module, than you will down in the everything else module. You personally might not have much code in those layers, but if you imagine the sheer amount of coding behind Entity Framework, or a different ORM, or the ASP.NET Web API, you’ll see why that layer is so thick.

Here’s the example, reimagined:

// Exposed via BLL DLL
public enum EntryTypes { Debit, Credit }

public class Transaction
{
    public Guid Id { get; }
    public Guid Account { get; }
    public DateTimeOffset Time { get; }
    public EntryTypes Type { get; }
    public double Value { get; }
}

public interface ITransactionManager
{
    Transaction Deposit(Guid account, double value);
    Transaction Withdraw(Guid account, double value);
}

public class TransactionManager : ITransactionManager
{
    IPersistence Persistence { get; }

   public Transaction Deposit(Guid account, double value)
   {
       // create a new transaction
       var transaction = new Transaction();
       // setup transaction
       Persistence.CreateTransaction(transaction);
       return transaction;
    }

    public Transaction Withdraw(Guid account, double value)
    {
       var account = Persistence.ReadAccount(account);
       if( account.Balance < value )
            throw new InsufficientFundsException();
       // create a new transaction
       var transaction = new Transaction();
       // ...
       
       Persistence.CreateTransaction(transaction);
       return transaction;
     }
}

// Exposed via DAL DLL
[Table("Transactions")]
internal class TransactionEntry
{
    public Guid Id { get; }
    public Guid Account { get; }
    public DateTimeOffset Time { get; }
    public EntryTypes Type { get; }
    public double Value { get; }
}

[Table("Accounts")]
internal class AccountEntry
{
    public Guid Id { get; set; }
    public string Owner { get; set; }
    public double Balance { get; set; }
}

public interface IPersistence
{
    void CreateTransaction(Transaction entry);
    Account ReadAccount(Guid accountId);
}

public Database : IPersistence
{
    public void CreateTransaction(Transaction entry)
    {
        // translate the transaction to a transaction entry 
        var entry = new TransactionEntry(); 
        // ... copy the fields
        // Code to store the table entry into a database.
    }
    // ...
}

 

Now, the Business Logic Layer has zero knowledge of anything other than it’s own logic. So lets look at the benefits:

  1. Any clients of the API won’t know about the persistence (so I meet my design principle #1).
  2. We haven’t coupled our Business Logic to our persistence. So we have the flexibility to change our storage medium, or have different store implementations.
  3. Our Unit Tests will now be flexible to any of those changes. Not like before where the unit tests were directly coupled to the table classes. Before we had to use them to check proper output from the BLL.

Overall, I learned a lot from this little venture down Architecture Alley. I hope you can learn something from tale of the adventure too.

Happy Coding!

PL