blog.christoffer.me

Hi, my name is Christoffer and I am an Internet addict.

2014-12-15 18:38

The "Caller Is Always Right" software principle (or why we should have more viking hygiene behavior in software development)

When I was a kid and learnt about the vikings for the first time, I also heard about their "alleged disgusting hygiene behavior". Especially regarding the stories where they passed around a bowl of water, where it starts with that the first person in the chain gets a bowl of clean fresh water, who then cleans themselves with the water, to later on pass the bowl down to the next person in the chain and so on.

Even though this ritual is (thankfully) less common today, it is something I kinda wish we had more of in software development. Hold on now. Let me explain.

The goal: The user should be able to logout

Let’s say you a functionality or a requirement that needs to be added in your software solution. For example this user story for a generic web solution:

As a User

I would like to logout from the website

So that I can safely leave the computer without leaving my account exposed

Users should be able to logout from the website once they have logged in. Pretty basic stuff.

However, if you create a road map of this new requirement across the different layers and functionality it impacts, it could look something like this:

Starting from the User interacting with the user interface and ends up with maybe a flag getting updated in the database. In order to implement this feature, there needs to be some kind of a communication between all these different parts - regardless if its simply invoking a method in an another part of the code or if it is sending a well defined JSON over HTTP to the web server.

The risk is that the back-end could dictate how the UX should be

So who decides how these API and interfaces between the different parts should look like?

There are a lot of discussions regarding patterns and principles about this, such as Component Based Design, Defensive Design and Design by Contract in order to maintain Separation of Concerns.

However I often always see flows like this:

Maybe you recognize this?

Here different parts of the software solution dictates how the caller and callee should behave in order to be allowed to interact with logic. In certain situations this is normal, such as using a third party database - which is totally fine - but in certain situation having a non decisive pattern like this could bubble up and compromise both the code quality by adding redundant boilerplate code the caller is not interested, or even worse, compromise the whole user experience.

A basic example of this is that the logout logic might expect both the username of the user and a boolean that indicates if the user is logged in our not (true equals the user is logged out) as arguments, which gets bubbled up so that the front-end developer needs to specify this in the JSON that is sent to the web server as well:

{
    "action": "logout"
    "username": "john",
    "loggedOut": true
}

It makes no sense for the front-end developer to provide these details. What they really would like to do is to send:

{
    "action": "logout"
}

Since (obviously) the user that should be logged out, is the one who is actually logged out (and the back-end should know who that is) and calling this API it should be obvious the user should be logged out (compared to getting logged in).

The solution: The caller is always right

According to me, APIs and interfaces should be design and dictated by the caller (the customer) and this should be done at each step in each layer - following the chain down - until it is no longer possible. Pushing down any eventual "ugly" or "messy" code to the very end to be sorted out.

Similar to what the vikings did with the water bowl when passing it down the chain, making it as good as possible at each step and forcing the receiving sort out any discomforts.

This means that for each step we should ask the question "What is the most simplistic and best way to solve the task, from this point in the code?" starting with the user experience; "What is the best user experience to allow the user to logout?" and then moving on towards "What is the most simplistic way for this JavaScript controller module to invoke the JavaScript back-end service module, asking it to log the user out?", and so on.

Using the SOLID-principles here, for example, could be great idea to answer what the "most simplistic" or "best way" is, as those principles help developers structure and design object oriented code.

This will of course impact the front-end code but then the front-end code gets the opportunity to ask "What is the most simplistic and best way to notify the web server that the user should logout?" and we maybe end up with this simple and clean JSON structure:

{
    "action": "logout"
}

Following this principle will make your solution more simplistic and stream lined by removing all the redundant and non-essential information for the given responsibility while keeping Separation of Concerns.

Reddit discussions about this post

Search the site

About Christoffer

Christoffer is a software and web developer, with more than 15 years experience of the Java language, now focusing on becoming a JavaScript and Dart Ninja.

Always interested in learning new and exciting new technologies and solutions within software- and web-development and the Internet, while suffering from the classic "I can't stop thinking" syndrome.

Currently working as a JavaScript Web Developer at QlikTech, while working on his own ideas and projects via his own software company during his spare time.

Please keep in mind that any opinions expressed here are Christoffer's own opinions and does not necessarily reflect those of his employer, or any other companies, organizations, groups or individuals.

Previous posts