Effective Knowledge and Experience Handovers

Over the last two months I’ve been working my way through a handover process as I prepared to leave the company where I’ve been working for the last eight years. This got me thinking a lot about what is a handover and how can it best be executed…

What is a handover?

The traditional view of a handover is where the employee who is leaving directly trains their replacement(s) in all the aspects of their job. However, for me this raises a number of questions and concerns:

• Why is the knowledge and experience of the leaver not already spread among multiple people in the company? Running with silos of knowledge owned by a single employee is a high risk strategy: that employee may suddenly be taken critically ill or suffer a serious accident.
• Why is much of the knowledge and experience of the leaver not already documented in diagrams, playbooks or procedures? Having details stored only in employees’ heads and in their rough form notes prevents the easy transfer and preservation of that knowledge and experience.
• What if there aren’t any direct replacements to handover to? It may have been impossible to recruit a replacement in time or the department may be restructuring and the leaver’s role may no longer exist going forward.
• What if the replacement has a different set of skills, experience and perspective on how to undertake the role? There may be better ways to do the job that the leaver hasn’t explored and just indoctrinating the replacement to do exactly what the leaver did is likely not the most effective approach to move forward with.

Clearly this traditional approach of taking someone new and just showing them how to do your job isn’t effective. So, is there a better approach and what should it be? Having gone through the process, my definition of an effective handover is now:

To ensure that knowledge and experience are preserved and communicated in such a way that they are accessible to everyone within an organisation, even those that arrive after the source of that knowledge and experience has departed.

Therefore, by definition this suggests that handover is more about producing durable materials and resources (as well as conducting direct knowledge transfer between individuals).

Types of knowledge and experience

While working through how best to communicate and preserve my knowledge and experience it became very obvious that this information was divided into two very clear categories:

• Explicit knowledge and experience - that which is clear and without vagueness or ambiguity.
• Implicit knowledge and experience - that which is understood but not described clearly or directly, and often using implication and assumption.

How these two types of knowledge and experience are identified and dealt with in a handover are very different.

Explicit knowledge and experience

Ideally in a well functioning engineering team this explicit knowledge should already be captured and widely used, so there should be a minimal need for handover in this area.

Examples of how this explicit knowledge is captured include things like:

• Having architecture diagrams and descriptions that are kept up-to-date as the system landscape changes.
• Having a record of key architectural decisions, why they were made and what alternatives were considered.
• Having documented processes where these are necessary. Examples of these include:
  • Processes for onboarding new team members
  • Definitions of done
  • Process for releasing code to production
  • Escalation processes for any production incidents
• Having Engineering Guides and Playbooks that detail things like how to configure systems, housekeeping tasks, build pipelines and so forth.
• Readme files in code repositories that detail what they do, how to build and use them, key dependencies etc.

If these are not already available then the first stage of handover work should always be to ensure that any of this explicit knowledge that the leaver is holding is captured. This likely involves a fair bit of document writing, updating knowledge bases and so forth. It’s also wise going forward to ensure mechanisms are in place within the team to ensure that this situation doesn’t occur in the future!

There is also great value to just surfacing and sharing this explicit knowledge. Some members of the team may not be aware of certain topics, others may have forgotten. There may also be team members who perhaps learn better from verbal communication and interactive sessions than from reading documents.

I found great value in being able to do interactive handover sessions, drawing on whiteboards, looking through code and so forth. This provides the team with good context on each subject which they can now use as a primer for diving into the more detailed information captured in the diagrams and documents.

An additional benefit I found when doing interactive sessions was that often a question or discussion topic would arise that I realised wasn’t already captured somewhere. This then highlighted the need to go back and improve on the store of knowledge, to ensure that assumptions or omissions became part of this explicit information set.

With hindsight there would have been great value to recording these interactive sessions and including them within the explicit knowledge set as well so that people not yet part of the team could utilise them as part of their onboarding process.

Implicit knowledge and experience

This part of the handover process is much more challenging. Most people, after working in a job for a long time, will have things that they just ‘know’ without realising that other team members may not ‘know’ the same things.

Some examples of this implicit knowledge and experience include:

• Handling a support issue and being immediately able to point to the cause of the problem.
• Seeing a particular error line in a log and being able to go to the exact module and piece of code that is the likely root cause of this issue.
• Getting a vague requirement from a customer and immediately understanding exactly what it is they are asking for, because someone asked the exact same thing in the past.
• Doing an admin task that seems so trivial that it just never occurred to write it down anywhere.
• Subconsciously following a process from the past that may not have been effectively communicated to newer team members.

The big question I focussed on as part of my handover was how to actually identify this implicit knowledge. In the end I came up with two specific techniques that I felt worked well for me:

The first approach was a forensic analysis of emails and our issue tracking system. I found great value in the ‘sent mail’ folder looking for conversations that I might have contributed ideas or opinions in. The history of tickets in the issue tracking system was also incredibly useful. In particular I focussed on tickets raised by support and internal defect tickets; those where I had collaborated but not directly owned were a particularly good source of implicit knowledge.

The second approach was much more of a meditative one. Firstly I spent time thinking over all of the tasks that I carry out on a day-to-day basis, with a focus on both periodic and adhoc items. Replaying questions from the support team was also very useful. Secondly I made a list of all the projects that I had worked on and did the same exercise, thinking over any previous admin, support work and conversations with customers.

A small number of items that came up from these approaches were clearly explicit knowledge that just wasn’t captured, so this was added to the appropriate places. The remainder were very much things that were known, but vague and rather undefined. Clearly people should be aware of and have a ‘starter’ should it become necessary to work on them. However none of these additional items were clear enough to make explicit or significant enough to require dedicated interactive handover work.

Capturing these implicit items was where Playbooks really came into their own. For each identified item I was able to create a section that considered:

• How does the item get noticed, reported or spotted?
• Are there any particular times or schedules that are appicabvle to the item?
• What are the symptoms that might point to the item? How might these manifest themselves?
• Has this item or question occurred in the past? How was it resolved then?
• What resources or information are needed to investigate or diagnose?
• Where should someone start looking?
• What are the possible answers or solutions? Have any been considered or discounted in the past?
• Are there any new processes that could be documented?
• What further information would be useful to capture so that implicit items could be converted into more explicit knowledge?

At the end of the process I was able to provide a Playbook of ‘starters’ to help future team members who encounter similar or closely related items from having to start from scratch.

Conclusions

A quality handover should include three elements: make sure all explicit knowledge and experience is captured; carry out interactive sessions to provide context and an entry point to this explicit content (ideally record them and add them to the content); and identify implicit knowledge and experience as record this as Playbook ‘starters’ that are available for team members to build on in the future.

My handover process was also a welcome reminder to make sure that explicit knowledge and experience is captured and updated continually. Don’t leave it until someone is leaving the team before you start generating diagrams, documenting processes and creating Playbooks for important activities.

The Value of a Safe and Open Interview Process

I’ve recently been interviewing for a new role. During this time I went through the interview process with three different companies. Two of these I already had in progress before finding the third role (which was the one I really wanted). Each offered a very different approach to the way they structured and conducted their interviews.

At the end of these processes I had very different emotional feelings about each of the three companies and roles. This got me thinking about what factors resulted in these different emotional responses.

Company A - Traditional Interview Process

This company had a fairly traditional interview process divided into four stages:

• An initial short chat with a member of the Talent Team to make sure that the role was a good fit. There’s no point in pursuing an expensive and time consuming series of interviews if the role is not a good fit for the candidate or visa-versa.
• A technical interview with two Engineering Team members talking through experience, knowledge and approach, with a few technical and design questions along the way. This also acted as a chance to discuss and ask about engineering culture.
• A problem interview, which for this company was conducting a code review on an example pull request. This was carried out in a low-pressure way where I was given time to do the review without the interviewers being present, followed by a short discussion of the points I had identified at the end. (Kudos to the person who wrote the code to review, it was a masterpiece of how to cram as much bad coding and design practice as possible onto a single page!).
• A final chat with the Engineering Manager (which I didn’t complete as I had already accepted one of the other roles by this time).

Overall I came away from this interview process feeling fairly neutral about both the company and the role. There was nothing that made me feel uncomfortable or unsettled, but at the same time I didn’t come away from any of the interviews feeling super excited or energised by the process.

They created an environment where I was able to feel fairly open to answering their questions, but still feeling that there were certain questions that they wanted to hear me give model answers to and others where the answers had to be correct.

I expect that this is the default experience for many people as they go through the process of finding their next role, but is this really the best we can do?

Company B - Toxic Interview Process

The second company I interviewed with had an interview process that I can only describe as toxic. I made it to almost the final stage of these interviews, but after my experience, there was no way I would have wanted to go and work for them anyway (even though they were the most high profile and highest paying of the three roles).

First off, before you could even enter their interview process you had to complete an online, timed, coding exercise. This involved two tasks where you are presented with a short problem statement, an empty code template and a set of unit tests (most of which you can’t see the inputs or expected outputs for). You then have to code up a solution that solves the problem and makes all the unit tests pass. All this takes place in an environment with a big countdown clock in the corner that ticks away your remaining time.

In my experience, there are very few people who can just sit down and pick up coding kata problems like these and produce great results. In order to be successful you have to have practised many times on similar tasks before actually taking the test. These practices also get you familiar with how the site doing the testing works, how it describes its problems, what sort of things it tests for and so forth. The net result is that to be able to pass the 90 minute test you also have to additionally invest a number of hours of practice time as well, and this is before you even know if the company or role is a good fit or not.

I also have some very specific complaints about these sort of logic/coding puzzle timed tests:

• All they prove is that you are good at logic/coding puzzles - they bear little resemblance to most of the engineering you will actually be doing in your job.
• A lot of them require you to just ‘see’ the solution, and, if for that particular problem, you don’t have that immediate insight, then it’s almost impossible to complete a solution, as you just don’t have enough time to work through it and create working quality code.
• Some people who are great engineers just don’t thrive in situations where there’s a countdown timer or someone watching their every keystroke.
• These tests may also exclude people who feel less confident or a bit anxious from even being able to access the interview process at all.
• They can create stress and discomfort, especially if the candidate is struggling with the particular problem they have been presented with and the clock is draining away.
• Unit tests where you cannot see the input or the expected output, only that they are failing provide minimal value or oppertunity to improve your solution and just add additional stress and pressure.

So, I did manage to pass this initial screening test. Even though my first impressions weren’t great, I decided to continue with the process just to find out more about the role, team and company - you never know, it may just have been some poorly considered HR requirement.

The next steps were multiple technical interviews with various Engineering Team members that all followed a similar pattern:

• A brief discussion about the role or some aspects of the project or engineering culture.
• A bunch of fairly detailed technical questions covering skills and previous experience.
• Yet more logic/coding exercises carried out live with the interviewer(s) watching and commenting on every line you wrote and expecting you to both code and narrate your thought processes as you did so.

There were a number of aspects to these interviews that turned them into a hostile and stressful environment:

• When discussing projects or processes the interviewing engineers came across as acting in an incredibly superior way, sometimes sneering if your answer wasn’t perfect or you previously haven’t been working to the specific ‘variation’ of scrum that their teams have adopted.
• They presented a demeanour of making you feel small or unworthy if you didn’t immediately know the Big O notation for a specific sort algorithm or couldn’t immediately code out a fully working, super efficient implementation of their chosen logic/coding problem.
• I got the feeling that often they were trying to catch me out and just waiting for the moment to pounce: especially if I gave a slightly wrong or incomplete answer to one of their questions.

The result of this sort of interview approach is that I started to feel stressed and pressured. Every question became a panic decision between do I give the answer I thought was right vs the risk that the answer might be wrong vs admitting that was something that I didn’t fully know. Rather than opening up to them I was being forced to close down. Ultimately I just didn’t feel safe or supported in that interview environment, started to doubt my own abilities and began to become flustered and unable to answer or write code any more.

At the end of each interview, the overwhelming emotion that I experienced was one of relief that the ordeal was over. No excitement about the role or the company was generated: just relief. After the final interview with them I was left visibly shaking from the release of stress tension built up over the duration of the interview.

Edit: Having thought about this more, I'm sure that this company didn't set out to create an interview process that created these emotions. I believe they probably have the goal of selecting only the very best technical candidates. Their selected solution for doing this was to focus heavily on processes that test primarily for technical skills. The unintended side-effect of this being that they have less time to focus on cultural fit and empathy for the candidates. /end

If that’s their process for finding the ‘right’ people, what would they be like to work for? A culture that encourages that sort of pressure on interview candidates surely isn’t an enjoyable, safe and supportive place to work? Would the type of people who were actually able to make it through the recruitment process be the kind of people I would want as my future colleagues?

In the end they decided not to continue with the final stages of the interview process with me. I wouldn’t have gone for another interview with them anyway. I’ve never been happier to drop out of the running for a new job!

Company C - Safe and Open Interview Process

The final company I interviewed with followed a process that was a world apart from my other two experiences. This process was probably the most detailed and time consuming of the three, but every aspect of it was thoroughly enjoyable, engaging and enlightening.

First off was a chat with the Engineering Manager who I would be working with. This was about as far away from a technical interview as you can get. We just chatted. He spent a lot of time telling me about the company, the product and the culture. Then I was asked a simple question (I can’t remember the exact words, but it was something along the lines of): “What’s your first impression, what excites you about this role?”. What a great way to assess a candidate. If they aren’t excited by what they’ve heard then why would you want them in your team? As a candidate, if the role and culture aren’t exciting then would you really enjoy working there? Would you grow? After that we just chatted generally about experiences, background and so on.

Particularly interesting was that the chat was conducted in a way that felt safe. It was easy to open up, admit answers I didn’t know; ask questions that might seem strange; talk about times when things I did went wrong. The overall feeling was that the interview was about getting to know each other rather than trying to judge. I finished this step excited and already knowing that I really wanted this job.

The next stage of their process was a take-home exercise. I know some people aren’t a fan of these, but I’ve always found them to be quite an enjoyable way to demonstrate my abilities. If they are structured right then they allow you to show problem solving, technical approach and code that is realistic to what you would typically produce (as opposed to trivial/funky/clever code that solves a specific logic problem).

In this particular case the exercise was closely related to their product, so it almost felt like you were already working on something related to the job. The exercise was timeboxed to three hours (which is often a criticism of take home exercises that are open ended and thus candidates feel they have to dedicate a huge chunk of their life to completing them). I spent a day mulling over the problem in my head then sat down over a couple of sessions and produced my submission. I was really enjoying the problem so I even carried on for a few more hours after submission to improve my solution and solve a couple of little areas that I hadn’t quite got right.

My submission was reviewed and I was invited back to the next stage of the interview, which was to talk about what I had done. This was carried out with two members of the Engineering Team that I would be working with if successful. Again this was conducted in a way that was structured to be entirely safe and open. They seemed really interested in what I had done and how I had done it - not some kind of faked interest, but genuinely interested. At no point was there ever any judgement on the approach taken, it was always a discussion on the reasons and the thinking behind a particular approach or technique.

Feeling comfortable and secure, I found it easy to be open and honest about where I had made good or bad decisions and how I would do things differently as I iterated over the solution. This enabled much more discussion rather than it being a question/answer driven session. I was not only able to get a sense of how they worked as a team and how strong their engineering practices were, but also who they were as people - something that’s generally really hard to get during a typical interview.

Next up was another session, this time on talking through how I would go about solving a particular engineering problem. Again this was a problem relevant to their domain and product so it felt like I was actually working with the team rather than being assessed. This was also another great example of creating a safe interview space where it was easy to be open and explore different avenues. No suggestion was wrong or dismissed, I was free to explore avenues that didn’t go anywhere or solutions that might be a bit unusual. It was easy to ask questions about what might or might not be possible. The discussions were all about the directions taken to solve the problem, why they might work or not and how my thinking process worked to get there. Again this was very much a two-way process of how I would fit in with the team but also how the team would work with me.

I left both of the above sessions feeling even more excited about the role, excited about the people I would be working with and with a sense of comfort that I would be able to bring skills and ideas that would enrich the team and that I would get the same in return. That’s a really positive feeling to leave a technical interview with!

The final interview stage was back with the Engineering Manager again, this time with the Product Owner involved as well. Again this worked as much more of a discussion process rather than an interview. The PO was able to enthusiastically talk about the product and the vision for the future. There were ample opportunities to ask detailed questions and discuss thoughts. Finally there were questions around how I think about products, user experiences, technology and so forth. Again this was all conducted in a safe space where I felt at ease opening up with my thoughts and where I felt comfortable giving detailed answers and my reasoning behind them.

Overall this interview process was amazing. At every point in the process I felt able to give open and truly honest answers. After each interview I felt energised and excited. Suffice to say, when they offered me the position I jumped at the opportunity and I can’t wait until I join the team. In fact, I already feel part of the team just from the interview process and that’s a great feeling.

Conclusions

Thinking over my interview experiences there’s a few good takeaways that should be part of every organisations’ interview process:

• If an organisation can’t excite a candidate or the candidate can’t excite the team then the two may not be a good fit.
• Creating a safe interview space will encourage candidates to be more open and honest with their answers, offer up more details and be more likely to ask deeper questions. Both parties learn so much more about each other.
• Conversely, creating an interview environment that is hostile and stressful will discourage candidates sharing honest answers, will limit how much you can learn about them and ultimately will prevent them wanting to join your organisation
• Some exploration of technical skills and experience is always relevant but ensuring the candidate is a great fit to the team culture personality wise is far more important,
• During the interview, make the candidate part of the team and work with them as such. You will learn much more about who they are, how they work and whether they are a great fit than if you treat them as an outsider to interrogate.
• Empathy with the candidate shows that the team they will be joining cares, and for great people that’s often a far bigger selling point than financial rewards or interesting technologies.

The Importance of a Good Shard Key

In MongoDB (and many other database solutions) scalability is achieved by dividing your database into a number of smaller portions. Each portion is stored on a separate set of database nodes. The theory is that this approach allows your database to scale horizontally beyond the capacity of a single node and allows load to be spread more evenly across multiple clusters of nodes. In MongoDB this approach is known as sharding (many other databases call a similar concept partitioning).

When you deploy shards in MongoDB you have to select a field (or fields) that are present in each document as the shard key. The value of this field determines which set of database nodes holds a specific document. If you get this key selection wrong then the impacts on your system can be huge.

As an example of how shard key selection is vital, consider this real-world, non-IT example, which clearly highlights how a poorly selected shard key can massively impact performance of a system:

At the weekend I participated in a large Half Marathon event, with about 20,000 other runners. The number of bags to be stored while the race was on was too large for a single baggage tent, so the organisers had wisely decided to introduce a sharded approach by having two tents, each holding half the bags. Additionally, each tent was further sub-divided into separate evenly-sized sharded collections of bags, each managed by its own team of helpers.

Now, as a shard key the organisers had decided to use race number: a seemingly sensible choice given that this would be the single unique piece of information that every runner would have. The bag tents were therefore arranged so that tent 1 was for numbers 1 to 10,000 and tent 2 was for numbers 10,001 to 20,000. The sub divisions inside the tents were further broken down into 1000 number blocks (i.e. 1 to 1000, 1001 to 2000 and so on).

For pre-race bag drop off this sharding approach worked really well (the write scenario). Runners dropping off bags were nicely distributed across both time and the full range of values, so each tent and sub-division could work in parallel for the maximum write performance. This was clearly an excellent shard key selection for the write case.

The problem occurred at the end of the race when runners returned to the tents to collect their bags (the read scenario). Now, the organisers of the race had issued the numbers based on predicted finish time (1 for the fastest predicted finisher, 20,000 for the slowest): the result being that runners finished roughly in number order.

So, what happened then is that there was a initially massive read queue at tent 1 for the 1 to 2000 numbers, while the other shard nodes were almost completely idle. Then the queue moved to the 2001 to 4000 shards, and so on. Towards the end of the race, tent 1 was idle while tent 2 now had the read queues as the later numbered runners all finished.

We have a perfect case of a shard key that seems quite sensible by design but is actually fundamentally broken by the usage scenario of the system, in this case the (near) sequential arrival of numbers for retrieving the bags.

So, how can we solve this? Issuing the race numbers in a different order is one option, but a sequential numbering system based on predicted finish time is quite sensible for many other race organisation requirements. A better option is to change the shard key used by the baggage tents.

Basing the shard key around race number is still a good approach as this is the one piece of information guaranteed to be unique for each runner and the range of possible values is clearly defined and well distributed. Bag drop off (write performance) is never going to be a problem as runners will arrive fairly well distributed across both time and the race number range.

The challenge is coming up with a way of better distributing the bag retrieval (read performance). Fortunately with a sequential numbering system this is pretty easy. Rather than shard by the whole number, just shard by the last digit of the number: tent 1 – numbers ending 0 to 4; tent 2 – numbers ending 5 to 9. Then in each tent further divide into five separate shards, one for each ending digit. If finer granularity is required then within each shard it should be easy enough to sort and index by full race number.

Selecting a good shard key is hard. Considering both the write and read scenarios, and how the shard key will be utilised within these scenarios is critical. It can make a huge difference between a well-functioning system and one that fails to gain the benefits of the sharded approach.

Scala's Maturing Community

I've been involved in the Scala community and attending Scala conferences for about four years now. I've just come back from 2013 Scala eXchange, hosted by Skillsmatter in London. It was a great conference, one of the best I’ve been to, and the organisers and speakers should be thoroughly pleased with their efforts. One thing that I did think quite interesting was a significant change in emphasis from all of the previous Scala conferences that I’ve attended.

When I first started going to Scala conferences four years ago, the emphasis was definitely on an introduction to Scala. The talks focused on basic language features, how to use the collections libraries and core functional programming concepts. There were also some side talks about interesting libraries built in Scala, like Akka and Lift.

Last year the focus moved to a higher level, with more time spent on talking about where Scala was going and on more advanced functional programming concepts. There were talks focusing on things like Lenses and Monads and lots of detail about highly functional libraries developed using Scala. Presentaions about Akka and Lift were still present and people were starting to talk about Futures. In all of these talks, however, functional programming was the primary focus.

At Scala eXchange this year the emphasis was almost entirely flipped around. Most talks were about reactive programming using asynchronous approaches. Loads of stuff about Akka, actors, futures, events and the like. Some talks focused on Scala features such as macros and using type classes. However, there was very little direct talk of functional programming: it was just assumed that everyone present was using immutable data and following a functional programming approach. A huge shift in perspective from just a year ago.

I believe that this represents a massive shift in the maturity of the Scala community. We have moved from an immature group learning about how to use this exciting new language, how to work with immutable data and how to blend functional approaches into our code. We have instead become a group who are using this fantasic language and a set of fairly mature products and reactive techniques to build highly scalable systems. A huge leap in just a couple of years.

I remember a similar transition in the Java community when conferences went from talking about basic Java concepts like POJOs, collections and design patterns to talking about building complex solutions using advanced libraries like Spring and JMS. The Scala community seems to have made this leap much more quickly than the Java community did.

The one thing that worries me slightly about this change is that using immutable data and functional programming has almost become an unwritten assumption. Each presentation just seemed to assume that you would be programming in this way by default. While this is great for those of us in the community who have made this transition, I think we need to be careful not to skip this step for those people just transitioning into the Scala world.

The worst case would be developers transitioning from a language like Java straight into an asynchronous reactive programming model without first going through the transformation of thinking in terms of immutable data and functional programming. Bringing the concepts of mutable state and imperative code straight into an async world is a recipe for disastrous software projects. These in turn could tarnish Scala's representation and significantly complicate the life of those of us trying to bring Scala into traditionally conservative organisations and companies.

It's great the the Scala community has come so far and matured so fast. But, let's not forget the core concepts that underly this transformation. We must ensure that we continue to emphasise their importance as we move forward into the brave new world of highly scalable, asynchronous, reactive systems that Scala seems to the targeting so directly and successfully.

Coaching: How Not What

Yesterday evening I was playing a game of 5-a-side football (soccer to my American readers) with some friends. One of the players on my team was a particularly competent player who was also very vocal in offering advice to his team mates on what to do.

For example, when a player from the opposing team was approaching me with the ball he would offer sage advice such as "Don't let them get past you!". This was rather stating the obvious, as I was quite clearly not planning on letting the opponent go past me and take a clear shot on goal.

In this particular situation my challenge was not in knowing what I should do, but in having the skill and experience necessary to carry out the task. No amount of shouted commands were suddenly going to increase my skill to a level beyond that which I currently possess.

This got me thinking about how we coach people in programming and agile practices. How often do we say to someone something like "that needs to be refactored" or "you need to keep your functions small"? Or, we might say to an agile team "don't overcommit yourselves this sprint". All of these are instructions to do something, made with the assumption that the people receiving them have the skill and experience necessary to carry out the actions.

What if, like me on the football field, the recipients of these instructions knows what they should do, but not how to do it. Clearly we are not being successful coaches in these cases. We need to focus much more on the how rather than the what. Advice offered should be enabling, providing the recipient with a way of learning and gaining experience.

For example, "if you pull this bit of code out into a separate function then this loop becomes much simpler" is much more helpful than "that needs to be refactored".

As coaches we need to be mindful of how we communicate in order to improve the people under our guidance. It's very easy to let it slip and just become another player shouting advice to those who haven't yet gained the skill necessary to implement that advice.

Fast Track to Haskell Course

I've spent the last two days on a Fast Track to Haskell course. It was a very interesting two days and I learnt a huge amount. The course was taught by Andres Löh from Well-Typed and hosted by the excellent people at Skillsmatter.

I went into the course having read the superb Learn You A Haskell book and having built a couple of experimental Haskell programs. From that starting point there was not a huge amount of content in the course that I was not aware of. However, it was great to have my learning verified and my understanding in many areas significantly improved. There were also a few things that changed my thinking on certain topics. All in all, a well spent two days.

The first day started with a whistle stop tour of the Haskell language and how to build things in it. There were plenty of excellent exercises to help cement learning and understanding. Then we looked in more detail at types and how to reason about software using types. The day concluded with looking at some more advanced type concepts including higher-order functions and type classes. The second day followed on with some more about types and then went on to look at how Haskell deals with I/O (which is very different to most other languages I have encountered). The rest of the day was then spent looking at common patterns that can be found in Haskell code and how these can be generalised into concepts such as Functors and Monads. Plenty more exercises followed.

I will now be going away and working on some private projects in Haskell, with the hope of attending the advanced course some time later this year. In the mean time, this blog post looks at some of the key things that I came away from the course with and how they relate back to the Scala and Java that I tend to do for my day job.

Focus on the Types, they are the API

When using an OO language, such as Java (or even Scala), we tend to think about classes, their interfaces and what behaviour they have, and then use this as a starting point to develop from. In Haskell you tend to think first about the types that are involved and then work forward from there. This is a very interesting approach as it makes it possible to think about a problem in a very general and quite abstract way without getting too bogged down in detail too quickly. The types become an API to your system (rather than the interfaces, methods and domain model in an OO solution).

My experience from the course was that this tends to lead to many more types and type aliases in Haskell than I would typically define in Java or Scala. However, this soon proves to be a huge advantage as it then makes it much easier to reason about what each function does/should do and makes its behaviour very clear via the type signature. I will certainly be looking at following this practice in any Haskell programs I write and also trying to introduce more types into my Scala code.

It's Pattern Matching and Recursion All The Way Down

In a language like Java there is nothing like pattern matching and recursion has to be used sparingly if you want to avoid blowing up the stack and writing poorly performing code. In Scala there is much more scope for both, although writing tail recursive functions is still very important to ensure that you get the best optimisations from the compiler. In Haskell, pattern matching and recursion are the bread and butter of the language. Almost every single function tends to be a pattern match on arguments and the language supports a naturally recursive style across the board. Given the lazy semantics of Haskell and the optimisation in the runtime for recursive algorithms this is the best approach for building programs in Haskell.

One area for improvement that I can see in my Scala code is to make more use of pattern matching, especially partial functions.

Thinking Curried Helps a Lot

In the Scala world we typically only curry functions when there are very obvious places to partially apply them. More often than not we just partially apply a function using the underscore for one of its parameters. This is needed to ensure compatibility with Java and the object-oriented model. However, in Haskell every function is completely curried. There are no multi-argument functions. Everything is a single argument function that returns either a result or another function.

Initially I found that this made sense in the model that I'm used to: partially applying functions. However, once it came to defining new types as actually being functions as well I found that this started to fry my mind slightly. The conclusion that I came to is that it's best to just think of everything from a curried mindset and throughout the course things gradually became clearer. This thinking is essential to understand things like the State monad (which I'm still not 100% confident about to be totally honest).

Parametric Polymorphism is Very Useful

One of my biggest take-aways from the course was how useful and important parametric polymorphism is. As an (overly) simple example, what does a function from Int -> Int do? It could return the same number, add something to it, multiply it, factor it, modulus it, ignore the input and return a constant - the possibilities are nearly endless. However, what does a function from a -> a do? Given no other constraints it can only do one thing - return itself (this is called the identity function - id in Haskell).

The ability to define functions in this polymorphic way makes it much easier to reason about what a function might do and also to restrict what a function actually can do. This second point greatly reduces the possibility of introducing unexpected defects or creating functions that have multiple interweaved concerns. As another example, consider the function: Ord a => [a] -> [a]. What does this do? Well, it could just return the same input list, but because it takes the Ord type class as a constraint it's quite likely to be some form of sorting or filtering by order function. As the writer of this function I'm restricted to working with lists and just using equality and ordering functionality so the possibility of doing anything unexpected is greatly reduced.

Parametric Polymorphism is possible in Scala, but not quite as powerful as there aren't type classes for may common concepts (e.g. equality, ordering, numbers, functor, applicative, monoid, monad etc.). Introducing Scalaz fixes this for quite a lot of cases, but that's not to the taste of many projects and mixed Scala/Java teams may find this a step too far. However, there's certainly more scope for using parametric polymorphism in everyday Scala code and this is something I'm going to work on ove the coming weeks (expect some more blog posts).

Don't Try to Over Generalise

Something that I've seen in every language is that once developers discover the power of generalising concepts they tend to go overboard with this. Remember the time when every piece of code was a combination of seven billion design patterns? The power of Haskell's type classes and parametric polymorphism makes it very easy to see patterns that may not actually hold. I can see that it would be very easy to waste a lot of time and effort trying to make a data type fit into various different type classes or trying to spot type class patterns in your code and pull them out into generic concepts.

As with any kind of design pattern, generalisation or similar, the best approach (in any language) is to just build what you need to solve a problem and then when it becomes apparent that it either fits an existing pattern or represents a general pattern then this change can be made as part of a refactoring process.

Try to Keep Pure and I/O Code Separate

Haskell's I/O model at first seems very different, unusual and restrictive. Once you get your head around it, it makes so much sense. Separating pure code from code that talks about doing an I/O action from code that actually does the I/O makes for software that is much more easy to reason about, test and reuse. Very powerful and something I'm looking forward to exploring more during my journey into Haskell.

In the Scala world, I'm not sure about the need to go to such lengths as using an I/O Monad or similar. However, I can really see the advantage of separating pure code from code that performs I/O. Having pure functions that transform data and then wiring them together with the I/O performing functions at a higher level seems a natural way to create software that is better structured and easier to test. I'll certainly be playing with some approaches in Scala to experiment with this concept further.

Functors, Applicatives, Monoids and Monads are Nothing Special

A final observation from the course is that many people learning and talking about functional programming get a bit obsessed with concepts like Functors, Applicatives, Monoids and Monads (especially Monads). What I learnt is that most of these are just simple patterns that can be represented by one or two basic functions and a few simple rules. Nothing more to them really. Certainly nothing to get all worked up about!

Yes, there's a great deal of skill involved in knowing when to use these patterns, when to make your own code follow a pattern and so on, but that's true of any programming language or design pattern. It's called experience.

Conclusion

If you are a Scala developer who is enjoying the functional programming aspects of the language I would certainly recommend taking a look at Haskell. I found that it clarified lots of things that I thought I understood from Scala but still had some doubts about. Haskell is, in my opinion, a more elegant language than Scala and once you start using it you realise just how many hoops the Scala team had to jump through to maintain compatibility with the JVM, Java code and object-oriented features. Over the two days I learnt a lot about Haskell, a lot about functional programming and a lot about how to get even more value from Scala.

Type Classes Make For Better Software Structure

When people usually talk about type classes in languages like Haskell and Scala they tend to be thinking of highly generic concepts like Ordering or Numeric operations. However, in some recent experiments with Haskell I have found that type classes can be very useful for more concrete things. When used appropriately they can lead to more loosely coupled software that is more flexible and easier to change.

I Just Met You, This Is Crazy, Here's My Number, Call Me Function?

As an example, let's consider a telephone number. Fairly simple right, it's a string of digits?

def sendMessage(toNumber: String, theMessage: Message)

Or perhaps we should create a type alias to give us some better info and scope for change:

type TelephoneNumber = String

def sendMessage(toNumber: TelephoneNumber, theMessage: Message)

But wait, I'm trying to build a library that sends messages to telephones and I need to know much more about a telephone number than this 'stringly' typed data is able to tell me. Things like:

• Is it in international format?
• What's the country prefix code?
• Is it a mobile number or a landline number?
• What is the area code?
• Is it some premium rate number?
• and so on…

The Naive Solution

It's clear that my 'stringly' typed representation is not sufficient for this task unless I want to encode a whole load of rules about the world's telephone numbering systems into my library (believe me when I say I don't!). So, a naive approach would be to introduce a new type that holds the information in a more usable format. Something like:

case class TelephoneNumber(countryCode: String, areaCode: String, number: String, isMobile: Boolean, isLandline: Boolean, …)

Unfortunately, this approach suffers from a whole host of problems, including:

• If I build my library implementation against this class then I can't easily change implementation details without breaking the API
• If I copy from an instance of this type into an internal representation then I have a lot of duplication and extra code to test
• If a client uses this type in their domain model they are tightly coupled to my library (and also a specific version of it)
• If a client copies from their own representation into an instance of this type there is more duplication and extra code to test

A More Object-Oriented Approach

So, how do we deal with this? Well what we need to do is separate the behaviour of a telephone number from its actual data representation. In an object-oriented language we would do this by introducing an interface (or in Scala, a trait):

trait TelephoneNumber {
  def countryCode: String
  def areaCode: String
  def number: String
  def isMobile: Boolean
  def isLandline: Boolean
  // and so on...
}

Internally in my library I write all my code against this interface without any care as to how the underlying telephone number data is structured. Client applications are free to implement telephone numbers in whatever way they wish, provided they also implement the interface that exposes the behaviour that my library needs. Yay, problem solved. Or is it? There's still one problem in this object-oriented approach: somewhere in the client code there must be a class that implements the TelephoneNumber interface. This is problematical in a number of ways:

• The class hierarchy of the client domain model is still quite tightly coupled to my library
• It might not be possible to modify an existing domain model to implement the TelephoneNumber interface (no access to source code, coupling restrictions etc.)
• If the client domain represents telephone numbers as Strings then this class can be extended to implement the interface

Both of the last two points would result in needing to implement the same sort of mapping layer to copy between representations that we already said lead to duplication and extra code to test.

How Haskell Does It

So, in a purely functional language that doesn't have the concept of interfaces how do we solve this problem. Enter the Type Class. These clever little beasties provide a mechanism whereby the required behaviour is captured as a series of function definitions (with possible implementations if available). For example:

class TelephoneNumber a where
    countryCode :: a -> String
    areaCode :: a -> String
    number :: a -> String
    isMobile :: a -> Bool
    isLandline :: a -> Bool
    ...

So far this looks pretty much like our interface definition above except that each method takes an instance of type 'a' as a parameter and returns the result. However, the clever bit comes in that we can implement the type class for any type in Haskell without needing to modify that type in any way. For example, we could easily implement it for Strings:

instance TelephoneNumber String where
    countryCode s = ...
    areaCode s = ...
    ...

Or our client code could define its own telephone number data type and an implementation of the type class along side it:

data UKTelephoneNumber = ...

instance TelephoneNumber UKTelephoneNumber where
    countryCode t = ...
    ...

The final change is then that we have our library function require that something implementing the type class is provided rather than some concrete data type:

sendMessage :: (TelephoneNumber t) => t -> Message -> IO ()
sendMessage to msg = do
    ...
    let cc = countryCode t   -- call function on the type class passing the instance we have
    ...

In this Haskell solution we have neatly decoupled the behaviour that our library requires of telephone numbers from the data type used to represent them. Also, any client code of our library does not need to couple its data structures/types directly to the library. They can define and modify them in any way they like. All they need to do is keep the instance of the type class up-to-date.

And Finally, A Better Scala Solution

As I have hopefully shown, the Haskell solution to the problem is both elegant and leads to cleaner, more loosely coupled code. So can we do something similar in Scala? Well, yes we can because Scala also supports type classes. They are a bit less elegant than Haskell, but they work just fine. First, we need to change the TelephoneNumber trait into a type class:

trait TelephoneNumber[T] {
  def countryCode(t: T): String
  def areaCode(t: T): String
  def number(t: T): String
  def isMobile(t: T): Boolean
  def isLandline(t: T): Boolean
  // and so on...
}

Note that all we have done is added a type parameter and modified all the functions to take an instance of that type. Notice that it's now almost identical in structure to the Haskell equivalent. Next we need an implementation of this type class. Let's define one for String:

object TelephoneNumber {

  object StringIsATelephoneNumber extends TelephoneNumber[String] {
    def countryCode(t: String) = ...
    ...
  }

  implicit def TelephoneNumber[String] = StringIsATelephoneNumber
}

I've put the implementation inside a TelephoneNumber object. If you are defining your own types, convention is usually that the type classes go in the companion object (e.g. for a case class UkTelephoneNumber the type class implementations would be in the UkTelephoneNumber companion object). This insures that the type class instances are always in scope when the type is used.

Finally, lets update our sendMessage function to work with type classes:

def sendMessage[T : TelephoneNumber](toNumber: T, theMessage: Message) = {
  ...
  val telNo = implicitly[TelephoneNumber[T]]
  val cc = telNo countryCode toNumber
  ...
}

Note the use of the context bound symbol ':' plus the implicitly function to define the need for and access to the correct instance of the type class.

So there we have it, an elegant Scala solution the overcome all of the coupling problems inherent with the object-oriented approach of implementing a required interface. When should you use this? My opinion is anywhere that two system components communicate, where that communication can be defined in terms of behavioural functions rather than actual data and where you want to minimise the coupling between them and the leaking of types from one component to another.

Encoding State Requirements in Types

In my previous post I looked at a simple way to eliminate conditional expressions by encoding them into the Scala type system. In this follow-up post I want to look at taking this further by using the Scala type system to encode state rules. The aim, as always, is to create code that fails to compile rather than code that fails at runtime. By doing this we also reduce the number of unit tests required.

The Problem

Consider a simple shopping workflow. I collect information about a Basket, the Customer and their Payment Method. Once I have all this in place I can create a processOrder function that completes the workflow process. As a naive starting point, lets encode this as a simple domain model holding optional values:

  case class CheckoutWorkflow(basket: Option[Basket], 
                              customer: Option[Customer], 
                              paymentMethod: Option[PaymentMethod])

  object CheckoutWorkflow {
    def empty = new CheckoutWorkflow(None, None, None)
  }                             

Then we need some functions that populate the workflow:

  def processBasket(workflow: CheckoutWorkflow): CheckoutWorkflow = {
    if ( workflow.basket.isDefined )
      throw new IllegalStateException("Basket workflow step already processed")

    // Do some processing...
    workflow.copy(basket = Some(basket))
  }

  def processCustomer(workflow: CheckoutWorkflow): CheckoutWorkflow = {
    if ( workflow.customer.isDefined )
      throw new IllegalStateException("Customer workflow step already processed")

    // Do some processing...
    workflow.copy(customer = Some(customer))
  }

  def processPaymentMethod(workflow: CheckoutWorkflow): CheckoutWorkflow = {
    if ( workflow.paymentMethod.isDefined )
      throw new IllegalStateException("Payment Method workflow step already processed")

    // Do some processing...
    workflow.copy(paymentMethod = Some(paymentMethod))
  }

Note that each of the above functions has a guard condition to stop them being called multiple times for the same workflow. Each of these guard conditions would require a separate unit test to ensure that it works and to avoid regressions should it be accidentally removed in the future.

Finally, we need the method to process the order. Given our domain model above, this class needs to contain some conditional check to ensure that all the workflow requirements are satisfied before processing of the order can commence. Something like:

  def processOrder(workflow: CheckoutWorkflow) = workflow match {
    case CheckoutWorkflow(Some(basket), Some(customer), Some(paymentMethod)) => {
      // Do the order processing
    }
    case _ => throw new IllegalStateException("Workflow requirements not satisfied")
  }

None of the above is obviously ideal as there are a number of places that have the potential to error at runtime. The conditionals pollute our code with non-business logic. Also, we have to write good unit tests to ensure all the conditionals are working correctly and have not been accidentally removed. Even then, any client may call our code having not met the requirements encoded in the conditionals and they will receive a runtime error. Let's hope they unit test as thoroughly as we do! Surely we can do better than this?

A Less Than Ideal Solution

Well, we could use the approach outlined in my previous post and use domain model extensions:

  case class WorkflowWithBasket(basket: Basket)
  case class WorkflowWithBasketAndCustomer(basket: Basket, customer: Customer)
  case class WorkflowWithAllRequirements(basket: Basket, 
                                         customer: Customer, 
                                         paymentMethod: PaymentMethod)

  def processOrder(workflow: WorkflowWithAllRequirements) = {
     // Do the order processing
  }                                         

While this does allow removal of all the conditionals and associated tests, it unfortunatley also reduces the flexibility of our model quite significantly in that the order that the workflow must be processed is now encoded into the domain model. Not ideal. We'd like to keep the flexibility from the first solution but in a type safe way. Is there a way that we can encode the requirements into the type system?

Levaraging The Type System

First, lets consider what we want to achieve. Our aim to encode unsatisfied and satisfied workflow requirements and only allow methods to be called when the correct combinations are set. So, let's first encode the concept of requirements:

  trait BasketRequirement
  case object UnsatisfiedBasketRequirement extends BasketRequirement
  
  trait CustomerRequirement
  case object UnsatisfiedCustomerRequirement extends CustomerRequirement
  
  trait PaymentMethodRequirement
  case object UnsatisfiedPaymentMethodRequirements extends PaymentMethodRequirement

Here we have defined requirement traits for each of the different workflow stages. We also defined case objects to represent the unsatisfied state of each requirement. Next we need to indicate the satisfied states, which are our actual domain object classes:

  case class Basket(items: List[LineItem]) extends BasketRequirement
  case class Customer(id: String) extends CustomerRequirement
  case class PaymentMethod(paymentType: PaymentType) extends PaymentMethodRequirement

Next job is to make sure that our workflow object can represent these requirements and be strongly typed on either the satisfied or unsatisfied state. We do this by adding type bounds to each of the workflow types. This also allows us to eliminate the need for the Option types. We also define an 'unsatisfied' instance as the starting point for our workflow:

  case class CheckoutWorkflow[B <: BasketRequirement,
                              C <: CustomerRequirement,
                              PM <: PaymentMethodRequirement]
                              (basket: B, customer: C, paymentMethod: PM)

  object CheckoutWorkflow {
    val unsatisfied = CheckoutWorkflow(UnsatisfiedBasketRequirement,
                                       UnsatisfiedCustomerRequirement,
                                       UnsatisfiedPaymentMethodRequirements)
  }

Now we need the functions that actually process each individual workflow stage. Note how each one defines type bounded parameters for the things it doesn't care about. However, for the stage that it actually manipulates it requires that it is called with the Unsatisfied type and returns the Satisfied type. Thus, you can no longer call any of these methods with a workflow that already has that stage satisfied: the compiler won't allow it:

  def processBasket[C <: CustomerRequirement, PM <: PaymentMethodRequirement]
    (workflow: CheckoutWorkflow[UnsatisfiedBasketRequirement.type, C, PM]): 
      CheckoutWorkflow[Basket, C, PM] = {

    // Do some processing...
    workflow.copy(basket = basket)
  }

  def processCustomer[B <: BasketRequirement, PM <: PaymentMethodRequirement]
    (workflow: CheckoutWorkflow[B, UnsatisfiedCustomerRequirement.type, PM]): 
      CheckoutWorkflow[B, Customer, PM] = {

    // Do some processing...
    workflow.copy(customer = customer)
  }

  def processPaymentMethod[B <: BasketRequirement, C <: CustomerRequirement]
    (workflow: CheckoutWorkflow[B, C, UnsatisfiedPaymentMethodRequirements.type]): 
      CheckoutWorkflow[B, C, PaymentMethod] = {

    // Do some processing...
    workflow.copy(paymentMethod = paymentMethod)
  }

Finally, our processOrder function becomes super simple. You just can't call it any more unless it has no Unsatisfied types:

  def processOrder(workflow: CheckoutWorkflow[Basket, Customer, PaymentMethod]) = {
    // Process the order
  }

One observation that was made to me by someone (a Java dev) who looked at my initial draft of the code was that the final solution looks more complex due to all the type bounds and that there's actually more classes due to the need to define the requirement traits and the Unsatisfied state objects. However, don't forget that this solution eliminates at least four conditional blocks and associated unit tests, simplifies others and also possibly reduces the number of tests that clients need to write on their code as well. Also, there's no possibility of runtime failure. If the code compiles then we have a much higher confidence that it will work. Well worth a tiny bit more type complexity in my book.

Eliminating Conditionals Using Types

I've been at Scala eXchange for the last two days. One of the topics that came up a couple of times was how the type system can be used to encode knowledge and rules, making it possible for the compiler to enforce these rather than needing unit tests to verify them. There were questions from some about how this actually works in practice, so I thought I'd produce some blog posts to demonstrate. This first one covers the most simple case.

Eliminating Conditionals Using Types

Consider the following (highly simplified) domain model:

  case class CreditCheckResult(statusCode: String, creditLimit: Int)
  case class Customer(id: Long, name: String, creditCheckStatus: Option[CreditCheckResult])

This model indicates that a Customer may or may not have completed a credit check. However, we only want to register the customer if they have successfully passed through a credit check. The registration function therefore looks something like:

  def register(customer: Customer): Either[String, String] = customer.creditCheckStatus match {
    case None => Left("Attempt to register non-credit checked customer")
    case Some(ccs) => {
      // Do the registration here
      Right(registrationCode)
    }
  }

This is a very common pattern in any places where an Option (or in Java a null) is used to indicate some conditional state (rather than a truly optional piece of data). The result is that we now need a unit test for both conditional cases:

  class RegistrationSpec extends Specification {

    "The registration process" should {
 
      "register a credit checked customer" in {
        // Test code here
      }
   
      "fail to register a non-credit checked customer" in {
        register(Customer(1L, "Test")) must_== Left("Attempt to register non-credit checked customer")
      }
    }
  }

However, we can use the type system to completely remove the need for this conditional check and thus remove an entire unit test case from our code base. How do we do this? By representing the different states that a customer can be in with different types:

  case class CreditCheckResult(statusCode: String, creditLimit: Int)

  trait Customer {
    def id: Long
    def name: String
}

  case class UncheckedCustomer(id: Long, name: String) extends Customer
  case class CreditCheckedCustomer(id: Long, name: String, creditCheckStatus: CreditCheckResult) extends Customer

Our registration method can now be greatly simplified:

  def register(customer: CreditCheckedCustomer) = {
    // Do the registration here
  }

And our test now needs to cover only the valid registration case:

  class RegistrationSpec extends Specification {

    "The registration process" should {
 
      "register a credit checked customer" in {
        // Test code here
      }
    }
  }

Aaaahaaa, I hear you cry, but doesn't the complexity instead move to the creation of the correct type of Customer? In some cases this might be true, but you could easily validate this by constructing customers using this code as part of the above test. Hopefully you will be using a functional programming style and you will already have a function somewhere that takes an UncheckedCustomer and transforms them into a CreditCheckedCustomer as part of the credit check process: which will already by type safe and tested!

I'll add some more examples of using types to reduce code and unit testing over the coming week or two.

The Next Innovation

Here's a little comic strip I put together ...

When you have created so many innovative products, it's always going to be difficult to come up with enough differentiation between one version of a product and the next to keep getting people to spend their cash. Creating an entirely new product line is even more of a challenge. I'm wondering where our favourite fruit named company is going to go next.

Unit Testing with MongoDB

Back in June I presented at the London Scala User Group (video here) on our experiences on a recent Scala project that used MongoDB.

One of the questions I was asked was how we go about mocking MongoDB for testing purposes (especially unit testing)? My answer was that we don’t! This raised a couple of eyebrows in the audience, but we’ve found this works just fine for us.

In this blog post I will explore our thoughts and reasoning in a bit more detail.

How do we test with MongoDB?

I’ll be honest: for the majority of our tests (even the unit ones) we just run against a local MongoDB instance. When we are testing repository classes we write tests against a real repository wired up against a real MongoDB instance. We assert against the contents in the MongoDB collections. In some cases, we even test service classes or even controllers with a live repository backend that writes to and retrieves from a real MongoDB instance.

“But you can’t do that!”, I hear you cry. Traditional thinking says that writing tests directly against the database will be too slow. We’ve actually found MongoDB (especially when running locally) to be so blindingly fast that we don’t need to consider doing anything else. For most updates and queries we tend to get sub-millisecond responses.

It’s also a hell of a lot easier and less fragile to back tests with real repository instances than it is to create and configure a load of mocks or strange database testing frameworks.

I’m pragmatic. If using a real database backend was making our tests run too slow or causing them to be too complex then I’d happily consider alternatives. Our experience with MongoDB is that it is both fast enough and that it’s query syntax is succinct enough that we don’t need to bother with those alternatives.

Do we use mocks at all for the database then?

Actually, I rarely use mocks in any of my Scala project now days. I’ve switched much more towards a style of isolating my calls to dependencies and then using mixin traits to override specific behavior for testing. (I’ll write a blog post about this approach soon).

From time to time we do need to write tests that make a repository dependency exhibit a specific behavior which is difficult to emulate against an actual database. In these cases we just use a custom test trait mixed into the repository in order to override methods to exhibit the behavior that we require. Keeps it simple and makes the tests much more readable and much less fragile than using mocks or other frameworks.

Making Agile Go Fast

Just recently I was speaking with a potential customer who had concerns about the velocity of their Scrum teams. They had recently (9 months ago) switched to an agile approach and had expected to get much more delivered than they had.

Now they were looking in to scaling up the number of Scrum teams on the project to try and increase velocity and deliver more quickly. In my experience of many agile projects, increasing the number of people on the project, especially one that is struggling, never has the desired effect of making things go faster. The advice to this customer was to therefore look at making their existing teams and process more effective rather than increasing the number of people on the project.

This got me thinking about what makes agile projects go slow. Across a number of projects that I have experienced, I’ve identified four common traits: two related to people and process and two related to technical concerns.

The Wrong People

Agile is all about using the right people. In fact this is true for any project or process, but for agile it is even more important. Use the right people and the agile process will work. Use the wrong ones and you will struggle.

The people who you don’t want on your agile project are those who are not disciplined enough to follow sound engineering practices and those who try to build complex frameworks/toolkits and who conduct personal science projects on your codebase. If you want to go fast then it’s vital that you have a clean, simple and well-refactored codebase that is backed up by a set of quality tests. Team members who don’t support this vision slow down the whole team.

To get back on track, remove those devs who aren’t following good engineering discipline and those who keep making things more complex. Bring in experienced agile developers to pair with the remaining team, giving them the responsibility of ensuring quality engineering practices are followed.

Putting The Process First

Another common mistake of companies starting out with agile projects is that they assume the process will make them go faster. Sorry to disappoint, but this is just not true. What makes agile teams go fast is creating open channels of communication and self organising and empowered teams.

If an organisation can’t create an excellent environment for communicating then no agile process will help. Agile helps teams go faster by eliminating the unnecessary documentation and waterfall steps. However, this information transfer must still happen and it happens through closer communication and collaboration.

Sadly, many organisations create agile teams and give them a process to follow but then insist on telling them how to organise, what tools and techniques to use, how to work and exactly what to do. This isn’t agile, it’s just another way of organising a traditional team. If you want agile to go fast then the team need total control over how they work and what they do.

To get back on track from here, relax on the process. Work on increasing communications. Give the agile teams the chance to decide how they will organise and work. Give them control and they will go faster. Agile is not a process, it’s about letting people get the job done.

Using The Wrong Technologies

So many agile projects struggle because they are using the wrong technologies. When this is the case it’s usually because the technology approach has been foisted on the team by an ‘ivory-tower’ architect or some senior manager who was wooed by the sales consultant from a large vendor. In other cases it may be that the team are forced into using a ‘corporate standard’ technology set.

In many cases the team will repeatedly identify the technology as a major factor in retrospectives. However, more often than not they will be told that this is not something that can be changed and that they have to stick with it. Why throw away hundreds of thousands or even millions on staff costs when backtracking on some poor technology choices would make so much difference.

Again, giving the teams the authority to make technology decisions is essential. Allowing technology choices to be reversed if they prove to be hindering delivery is also an important part of being agile.

Making The Architecture Too Complex

Many software systems are designed, or become, far too complex. In an agile environment this is a guaranteed way of making things go slower. Software must be kept as simple as possible so that it is easy to continually change and enhance.

If the architecture of an agile system has become so complex that it hinders development then it must be revisited and greatly simplified. Layers must be removed, interfaces reduced and code and technologies radically refactored to make everything simpler. Once that is done then the project must work all out on stopping it from getting more complex again in the future.

Only by using the right people, correctly empowered and communicating can the team have the ability to go fast and be truly agile. Only by making the correct technology choices, reversing bad technology choices and keeping everything simple can the ability to turned into real agile delivery.

Cucumber JVM Support for SBT

I am happy to announce release 0.5.0 of my xsbt plugin for cucumber. This is a major new update that finally switches from using the Ruby version of Cucumber (running under JRuby) to the newly released Cucumber-JVM.

Full details of how to use the plugin can be found on the github page: https://github.com/skipoleschris/xsbt-cucumber-plugin

A list of significant changes for this release include:

• Switched to cucumber-jvm
• Less configuration options due to no longer requiring JRuby
• Improved control of output options

Pairing is Wearing

In this post back in August 2011 I was talking about the many benefits of Pair Programming. Having now been full-time pair programming for almost an entire year, I wanted to mention one of the downsides that I have discovered.

A Holiday

I've just finished my holiday. It wasn't the best one ever, mainly due to camping in the UK in June: which meant heavy rain and strong winds. Still, we had a good time and it was very relaxing.

As the week progressed and I had a chance to relax, unwind and get some lie-ins I started to discover that my mind was starting to become more alert. I was feeling less tired. Great ideas were starting to flow again. It was at this point I realised just how weary I had been at the start of the holiday. I had known I was feeling pretty knackered, just not quite how much.

This then got me thinking as the the possible cause of this tiredness and how it could gradually build up over time without me being fully aware of it. I looked back at what I've been doing for the past year...

• I've been travelling a lot to get to/from work - but less than my previous job.
• I've been learning lots of new stuff - but I'm a compulsive learner, so nothing new here.
• We've put at least 3 major releases live - but I've put plenty of software live before.
• We've been pairing full time - this is new!

Is Pairing More Tiring?

The conclusions that I have had to draw is that working in a paired environment is more mentally tiring that working alone or individually within a team. There's more of a requirement to stay focused when working as a pair - it's particularly noticable when one member of the pair is feeling unwell or tired. Also while pairing you are multitasking more - writing code, thinking about solutions but also communicating your thoughts and maintaining a running dialogue. All of this extra work requires extra mental energy and thus increases fatigue.

So, how can we pair over a period of time without burning out? Here's some thoughts that I hope to experiment with over the coming months:

• Take more frequent and longer breaks than you would do while working individually. The productivity gain of working in pairs easily allows this to be supported
• Do a lot more walking at lunchtime!
• Try to provide team members regular tasks that they can undertake outside of a pair to give their mental energy drain a rest. Stuff that doesn't require extensive multitasking.

Anyone else got any thoughts or ideas?

Life Without Objects

Over the last few years I have been learning and experimenting with a wider range of programming languages. In particular I have started using Scala as my primary development language, adopting a more and more functional style. I have also become very interested in Haskell (a pure functional language) and Clojure (a modern lisp dialect).

I have therefore been moving away from the object-oriented development principles that have made up the bulk of my 17 year career to date. More and more I am beginning to feel that objects have been a diversion away from building concise, well structured and reusable software.

As I pondered on this topic, I realised that this isn’t a sudden switch in my thinking. The benefits of objects have been gradually declining over a long period of time. The way I use objects today is very different to how I used them when they were new and shiny. In this post I explore this change in my thinking about object-oriented development.

The Promise of Objects

Back in the 1990s, objects were new and exciting. The promise of being able to create reusable classes built around common design patterns was seductive. The ability to then combine these classes into reusable and configurable business components seemed like the Mecca of software development. New languages like C++ and then, slightly later, Java held the promise of a new way of building great software.

Business Components Aren’t Reusable
It didn’t take us long to discover that the ability to create reusable business components was just a giant fallacy. Each business is significantly different from another, even in the same industry. Each similar project has very different business rules.

The only way to build reusable business components at this level is to make them hyper-configurable by adding such things as rules engines and embedded scripting languages. Hardly a component model and more like a bloatware model. This promise gone, people either buy into the big bloatware systems (suckers) or build their custom business objects on a project by project basis.

Patterns Don’t Build Well Structured Software
The next thing we learnt was that excessive reliance on design patterns doesn’t lead to the good software structure. Instead it leads to software that is overly complex, hard to understand and difficult to maintain. Some patterns even turned out to be anti-patterns (the singleton pattern makes software almost impossible to unit test, for example).

We soon learnt to use patterns judiciously. More often than not it’s just cleaner to code the software as you understand the model rather than try to abstract it into a more generalised pattern.

Frameworks for Class and Component Reuse Give Few Benefits
Another early promise of objects was rich, tightly coupled frameworks of classes which when used together would make building applications from reusable component a breeze by hiding all the technical complexity and implementation plumbing. Think EJB and similar. Experience soon showed that these just did not work. They were just too restrictive and cumbersome for what people were trying to achieve.

These heavy-weight frameworks soon died out to be replaced with more lightweight libraries and toolkit type approaches. Collections of more loosely coupled classes that you can pull together as needed are now the preferred way to build software. Take just what you need and nothing more.

Inheritance Creates Brittle Software
The ability to support interface and implementation inheritance was one of the key tenets of object oriented software development. We could spot common code and behaviour and push this down into a shared base class so that future abstractions could benefit from having this shared code available to build on.

Sadly, this just didn’t work out well. Each sub-class turns out to be subtly different from its peers, resulting in lots of overrides of base class behaviour or making the base classes even more generic. The net result was super-fragile software, where any small changes to a common base class would break most, if not all, of the sub-class implementations.

These days we don’t use inheritance much, and especially not for creating technical base classes. Its use is pretty much restricted to interface inheritance to indicate an object supports a certain behaviour or to occasional domain models where there is a true inheritance relationship. Other than that we tend to extract commonality in to separate ‘mixin’ type classes and compose them together through an aggregation approach.

Violation of Encapsulation
Another key feature of the object-oriented model was the ability to encapsulate state and then expose behaviours (via methods) that access and update this state. Unfortunately it turns out that there are a large number of cases, where we are actually interested in the vales of the state rather than the behaviour.

For example, asking an object to render itself as HTML turns out to be a pretty poor approach. Knowledge of HTML rendering gets spread across the code base and a small change in approach causes us to change many, many classes. Instead we tend to pass the object to a dedicated HTML rendering/template component, which pulls the data values from the object.

Anti-patterns have even emerged around this to allow us to have light-weight objects that just encapsulate state without behaviour (Java Beans, Data Transfer Objects and so on). If we are doing this, then why not just work directly with first-class structured data as opposed to objects?

Mutable State Causes Pain

Another perceived benefit of encapsulation was the ability to mutate the state of an object instance without impacting on the clients that use that object. However, anyone who has built a significant sized object-oriented system can tell you stories of trawling through many files of code to find the location that mutated the state of an object to an unexpected value that happened to make your software blow up in a completely different place (usually where you output or store the state of that object).

More and more we now favour immutable state and stateless services so that these problems do not occur. There’s also the additional benefit that immutable state is a much better model for building highly concurrent systems and for getting the most out of modern multi-core hardware. It’s also far easier and less error prone than trying to work with threads, locks and concurrency safe data structures.

Behavioural Interfaces Cause Code Complexity and Bloat
One of the things we do frequently in object-oriented languages is create small marker interfaces that have just a single method. Any class wanting to support this behaviour extends the interface and implements the method. We can also declare anonymous implementations for ad-hoc use.

However, we have found that neither of these approaches are particularly good. Implementing the marker interfaces often pollutes classes with implementations that are not their direct concern (thus violating the single responsibility principle). Anonymous classes are just unnecessary bolierplate that makes our code more difficult to understand and maintain.

Life Without Objects

So, is it possible to go back on 17 years of experience and contemplate a life without objects? I’m not sure that I’m 100% there just yet, but using a multi-paradigm language like Scala is allowing me to overcome many of the limitations of the object-oriented approach.

For example, Scala’s support for mixin traits makes it almost unnecessary to ever use implementation inheritance. It’s rich collections framework plus the ability to use case classes to create data structure like concepts obviates working around encapsulation issues. A recommendation to use immutable data and collections makes code easier to debug and reason about. The ability to use functions as general abstractions and type classes to extend behaviour while maintaining single responsibilities makes it much easier to build well structured, reusable software.

In fact, what I find I am doing more and more is using simple objects in the form of case classes to represent data structures, with a few behavioural methods to simplify working with this data. Then I’m just using mixin traits as a modular approach for grouping related functions together. Then I’m combining these together to form components in which I compose together various functions that transform data from one for into another.

Perhaps I’m further away from the pure object-oriented approach than I’d thought. I’m certainly building smaller, cleaner and better structured software than I ever was before.

Option

In my previous post I introduced Dave and we looked at map, flatten and flatMap. In this new episode we take a look at the Scala Option type:

Here's some code...

case class Person(name: String, partner: Option[Person])


sealed trait Product
case object XBox extends Product
case class WeekendAway(person1: Person, person2: Person) extends Product

type Cash = Int
case class Purchase(product: Product, change: Cash)


def buyXBox(cash: Cash): Purchase = Purchase(XBox, cash - 20000)

def bookWeekendAway(p1: Person, p2: Person, cash: Cash): Purchase = Purchase(WeekendAway(p1, p2), cash - 15000)


val lucy = Person("lucy", None)
val dave = Person("dave", Some(lucy))
//val dave = Person("dave", None)
val wages = 50000

val purchase = dave.partner map (bookWeekendAway(dave, _, wages)) getOrElse buyXBox(wages)
println(purchase)

Map, Flatten and FlatMap

I've recently been working with some developers who are new to the Scala world. They've picked up the language really easily and in only a few week have become competent Scala developers. Who says it's too complex and difficult to learn?

Anyway, one of these developers is a visual thinker such as myself. We prefer communication through diagrams rather than words. While explaining Scala I've been drawing some pictures to illustrate some of the more interesting concepts. She suggested that I should publish these and we had the idea that an animation would be fun.

Here's my first animated post showing the concepts for Map, Flatten and FlatMap. It's a pretty amiturish stab at animation, but hopefully it explains the concepts while also adding a bit of humour along the way.

If you are interested here's the Scala code for the concepts covered in the animation:

case class World[+A](revolvesAround: A) {

  def map[B](f: A => B): World[B] = World(f(revolvesAround)) 

  def flatten[B](implicit ev: A <:< World[B]): World[B] = World(revolvesAround.revolvesAround)

  def flatMap[B](f: A => World[B]) = World(f(revolvesAround).revolvesAround)

  def get: A = revolvesAround
}

def lift[A](entity: A): World[A] = World(entity)

case class Person(name: String) {
  def smite = DeadBody(name)
}
case class DeadBody(usedToBe: String)
case class Insect(species: String)

def kill(p: Person): DeadBody = p.smite
def reincarnate(b: DeadBody): World[Insect] = World(Insect("ant"))

val dave: Person = Person("Dave")
val antDave: Insect = lift(dave) map kill flatMap reincarnate get 

println(antDave)

Done and Dusted

In a recent retrospective our team dug out our Definition of Done and gave it a good review. We ended up removing a number of unnecessary items. This got me thinking about what is Done?

In previous places that I have worked the Definition of Done was a long check-list of things that had to have been completed and verified. Is this the best that a philosophy that claims to value "individuals and interactions over processes and tools" can come up with? This got me thinking...

Isn’t Done actually just the state when the team agree that the story is complete? Why should it need to be any more than that?

Done: The state when all team members agree that the story is complete

We could expand this slightly to define the roles that the different team members play in this definition:

• Developers agree that the code is complete, tested and refactored to an acceptable standard
• QAs agree that the acceptance criteria for the story has been met, that the functionality works and that they have not found any defects introduced by the new feature
• BAs and POs agree that the feature meets the business objectives for the story
• (we could also add points for DBAs, Ops etc, as needed)

So, if we accept that the team can decide for themselves when something is Done, why do we end up with long checklists, often including a whole range of metrics? It could be because 'management' aren’t able to release their need to monitor everything and produce nice reports. However, it’s more likely a matter of trust.

Teams are just not trusted to self-organise and make good decisions. If the team say that a story is Done then for many managers there is an immediate suspicion that the team is not telling the truth and is trying to cut corners. They then require that there is concrete proof that this is not the case. This is despite the fact that a group of professionals all happen to agree that it is Done. It just doesn’t make sense.

If the team has never released a story as Done when it clearly wasn’t then why doubt they will suddenly stop doing this in the future? Show trust in the team that is delivering completed work.

If the team are marking stories as Done when they clearly aren’t then there is a much more serious problem with the team and they probably either need replacing, mentoring or a firm guiding hand. Adding a requirement to satisfy a long checklist and provide associated metrics will never improve a bad team.

As with many things agile, it’s not about the process: it’s about changing attitudes; it’s about trusting teams to deliver the best solutions possible; it’s about not bogging the teams down with unnecessary controls.

Sometimes you just have to be lazy...

...or, solving problems with lazy evaluation.

I’ve recently been working on a simple template system, which also has the potential to grow into a full-blown document generation system. The basic principle is that a document is composed of a number of fragments. Each fragment is called in turn to generate its piece of the document and these pieces are concatenated together to product the final result.

My first implementation was a super simple one. We just fold over the list of fragments, accumulating the output from each into a string builder. Each fragment may alternatively generate an error, which we collect along the way as well. At the end of the fold we return either the string document or a list of errors.

  def render(fragments: List[Fragment]): Either[List[String], String] = {
    fragments.foldLeft(RenderResult()) { (acc, fragment) =>
      fragment.generate fold (
        { err => acc.copy(errors = err :: acc.errors) },
        { text => acc.doc.append(text); acc }     
      )
    }.toEither
  }

  case class RenderResult(doc: StringBuilder = new StringBuilder(), errors: List[String] = List()) {
    def toEither: Either[List[String], String] = ...
  }

Now, this works great for documents of only a few kilobytes in size. However, as the documents grow to multi-megabyte sizes this approach becomes infeasible. The amount of memory required to hold the document being generated becomes huge. Multiple concurrent generations become impossible. We need a better solution.

The typical suggestion at this point is to stream output from each fragment straight into an output writer of some form rather than collect and build a string.

  def render(fragments: List[Fragment], writer: Writer): Option[List[String]] = {
    fragments.foldLeft(List[String]()) { (acc, fragment) =>
      fragment.generate fold (
        { err => err :: acc.errors },
        { text => writer.write(text); acc }     
      )
    }.getErrors
  }

Unfortunately this doesn’t work here because of the possibility that fragments may generate errors. We don’t want to stream out partially complete documents. We could output to a temporary file and then copy this to the ultimate output on success, but this seems like a less than ideal solution.

A common approach in an imperative style would be to first run a check phase to see if there are any errors and then run a second render phase to produce the output.

  def check(fragments: List[Fragment]): List[String] = 
    fragmens.foldLeft(List[String]()) { (acc, fragment) =>
      fragment.checkForErrors map (_ :: acc) getOrElse acc
    }

  def render(fragments: List[Fragment], writer: Writer): Unit = 
    fragments foreach { fragment => writer.write(fragment.render) }

However, in this case the building of fragments might be quite costly and we don’t want to have to process them once to see if there is an error and then again to render.

However, as we are using Scala and programming in a functional style, we have an alternative approach. Instead of returning a string or writing direct to a writer we can return a lazily evaluated function. This function can encapsulate all the side-effect generating logic of doing the actual write - which is also nice from the point of view of being able to reason about our rendering code.

  def render(fragments: List[Fragment]): Either[List[String], (Writer) => Unit] = {
    fragments.foldLeft(RenderResult()) { (acc, element) =>
      fragment.generate fold (
        { err => acc.copy(errors = err :: acc.errors) },
        { func => acc.copy(fragmentFuncs = func :: fragmentFuncs }     
      )
    }.toEither
  }

  case class RenderResult(fragmentFuncs: List[() => String] = List(), errors: List[String] = List()) {
    def toEither: Either[List[String], List[(Writer) => Unit] = {
      ...
      (writer: Writer) => fragmentFuncs foreach { f => writer.write(f()) }
      ...
    }
}

The way this works is that the render method folds over each fragment, asking the fragment to do enough work to be certain that no errors will occur (e.g. validate data, take a temporary copy of any volatile values and so on). However, it doesn’t need to do the actual string generation. Instead, each fragment returns a function that will be called at some time in the future (or an error). The render code then accumulates all these small functions into one larger function and returns this.

The returned function, when called, takes a writer and iterates over all the small string generating functions, writing the output of each straight into the writer. Job done and in a mere fraction of the memory required by the original solution.

In cases where you need to generate large amounts of data or where you want to delay side effecting execution to a well-defined location in your code then lazy evaluation is a great approach to follow.

NOTE: All above code example are significantly simplified from the real code in order to demonstrate the approach.