Performing a large code refactoring or implementing a new feature in a legacy codebase is a great undertaking for any team. Even in a well architected codebase, tasks will likely be complex and require careful thought. Such endeavours may span several weeks or even months, requiring a high level of communication, understanding, and agreement amongst the team.
Recently the Honeybees team decided to read The Mikado Method, and discuss our thoughts weekly as part of a book club. The aim was to learn new skills for large scale refactoring, as we are planning to refactor a sizable chunk of our codebase in the near future. To evaluate the technique, we decided to use it to change the logging library used in SQL Prompt.
The Mikado Method
The Mikado method is a technique used to explore and understand how a task could be performed, identifying the key actions to complete it. The first step is to define a goal. This should be the abstract idea that is to be achieved, for example:
“Replace the logger with an approved logging framework”
With the goal determined, the most abstract steps (prerequisites) to achieve the goal are added to the graph. Once the first level of prerequisites has been chosen, each leaf node is explored to discover its own prerequisites. This process repeats until all leaf nodes are relatively trivial tasks. As a node grows further away from the goal the task should become more concrete. The book tells us the nodes can be explored using either a depth-first or breadth-first approach. For us, the best solution was somewhere in the middle — explore each layer briefly and when there are no more obvious prerequisites, we drill down into one node depth-first.
The controversial magic of the Mikado method is that code changes are regularly discarded. During exploration, the goal or prerequisite is implemented naively and then a decision must be made to keep or discard the code immediately, based on whether the changes make sense and what errors have been introduced. This feels very unnatural at first as you may spend 15 minutes refactoring a class only to revert the changes. The key realisation here is the time has not been wasted! Instead the time has been used to learn about the code structure and expand the Mikado graph, hence creating a superior plan. Code changes can be stashed if they are valuable but currently produce non-trivial build errors. However, this increases the complexity of the process and the eventual merge may offset the time saved by stashing.
“If you are hacking the next step, you’d be building on assumptions and guesswork. Avoid the temptation” — A quote from our book club.
Once the graph has been explored to a reasonable extent and the resulting leaf nodes represent achievable chunks of work, we can begin making changes to the code. Decide on the most logical leaf node to start at and begin working towards the goal, completing each prerequisite one-by-one. By the time the graph is completed you will have a feel for where to start. Tick off each prerequisite when the code is committed.
The key thing to remember is that the graph should be treated as a living document, so making changes and exploring further during the work is acceptable and encouraged — we live in an agile development world after all!
The primary focus of the Mikado method is planning how a piece of work could be carried out. This is reasonable and it is an effective tool, however it’s far more valuable than that.
When working on a task that stretches over several weeks or months a developer may lose focus of the end goal or get lost in a task as more and more complexity is added. This can lead to scope creep and ultimately inefficient working. The Mikado graph allows work to be tracked and a clear working path to be visualised.
A piece of work completed by a pair or team, either as a mob or splitting up the work and coding asynchronously, must be well understood by all members of the team so that the result is what everyone expects. Using a graph to illustrate this allows the team to agree on the abstract steps that need to be taken, an end goal, and the direction to get there. This is particularly important where a team may be working remotely and quick discussions about the approach may be more challenging to coordinate.
Using the Mikado method allows an individual or team’s thought processes to be written down in a clear way that can be understood by someone who is not well versed with the problem. This means that during a refactoring code review where a reviewer may be faced with a 150+ file change pull request, the thought process and reasoning behind why a piece of code has been changed can be understood much more easily. This means that code reviews can be more effective and faster.
“The Mikado method is what an experienced developer would normally do subconsciously, plus the discipline and courage to undo changes” — A quote from our book club.
The Mikado method is a great refactoring tool for any developer. The method provides a great deal of support with longer running tasks, especially when working in teams. Making the steps to achieve success visible is particularly important in the remote working world. As such the Mikado method should be treated as both a refactoring and a communication tool.
Give the Mikado method a try and share your graph in the comments! P.S. we recommend using an online whiteboard app such as Mural.