This article is a revised version. It was previously published at refactoring-legacy-code.net published.
This is a series of articles. You can find the second article here:
Implementation of refactoring with the Mikado method
The first step is to use an experimental approach to develop a Mikado Graph were created. In each case, naive attempts were made to make the necessary changes to the code. All the problems that emerged during these experiments are described as Preconditions for the Mikado target have been transferred to the Mikado graph. As the individual preconditions build on each other and are therefore dependent, the Mikado graph not only contains the preconditions, but also represents the dependencies.
The Mikado Graph is therefore a directed graph. At the root is the Mikado goal, which is to be achieved by the individual refactoring measures. The Mikado goal can be something like "Save data in the cloud instead of locally" or "Fix errors when creating a new product".
Once the Mikado Graph has been created, the individual challenges are tackled. The refactorings are implemented in the opposite direction of the dependencies, from the leaves to the root. We now work in the opposite direction, from the outside to the inside. The individual challenges are solved and transferred to version control.
Please note that these changes on the Trunk be carried out, as they are of short duration. A Branch is not necessary because the changes do not take long and the result should potentially be deliverable. Automated tests should either already exist or be added in the course of refactoring. Finally, before committing to version control, it must be ensured that the change has not led to any defects.
The Mikado Method
The following illustration shows the Mikado method.
The Mikado target note
The aim of the change is noted at the beginning. This goal is driven by a customer requirement. A new feature or the modification of an existing feature as well as bug fixes are potential objectives of a change.
Implement the target or the current precondition naively
Now try to achieve the goal in a naive way. Go ahead and implement it. It is now important to find out what is standing in the way of implementation. This step is not about the final implementation, but about gaining knowledge. It is therefore okay to violate one or two clean code developer principles, as the code will be thrown away anyway.
However, you must not go overboard in this step. Keep pausing and checking whether you have reached a point where it might be time to note a gain in knowledge in the Mikado Graph. If your system suddenly no longer behaves as desired or the change causes many compiler errors in all possible places, you have reached such a point.
Is there a problem?
If you have made a change, you need to find out if there is a problem. It could be that the program is no longer doing what it should. Then there is definitely an error. If you have automated tests, you're in the clear, because then one might fail. Without tests, your only option is manual testing. If in doubt, assume at this point that something has broken.
Secondly, you may encounter problems in your code base. If you encounter a challenge during the naive implementation, you should also stop at this point. Typical challenges are dependencies. You suddenly realize that you have overlooked a dependency and cannot complete the change until you have eliminated or changed the dependency. Another typical challenge is the mixing of aspects. You realize that a method or class is not only responsible for one aspect, but that there is a jumble of aspects. To make good progress, you must first separate the aspects. Note the challenge as a precondition in the Mikado graph and consider the result of the change as a problem.
Does the change make sense?
If there was no error, you need to find out whether the change makes sense. The point here is to only transfer changes to version control if they make sense as a whole. This means that you should not check in any results that represent an unfinished intermediate step.
Typically, you only come to a positive decision here once you have started to implement the findings of the Mikado Graph sheet by sheet. In other words, you have not started with the goal of the Mikado Graph, but have selected a sheet of the graph and started to implement this prerequisite for the overall goal. Of course, at some point you should be able to come to the decision that the change makes sense. You are no longer in the experimental phase but are now in the process of implementing the knowledge gained sheet by sheet.
You should back up the change with automated tests. This makes it easier to find out whether the change makes sense.
Commit the changes to version control
If the changes make sense, transfer them to version control. In the Mikado Graph, tick the precondition because it has now been implemented. This results in new sheets that can be the target of the next change.
Has the Mikado reached its goal?
After the commit, you must decide whether the Mikado target has already been reached. If so, you are finished.
Searching for solutions
If there were errors, you must now look for a solution. Errors can occur at the program code level. For example, you may find that you can no longer compile the program when removing a dependency. Errors can also occur when executing the program. Your change has "broken" the program. In both cases, you need to look for solutions.
Note the solutions as preconditions in the Mikado graph
Once you have found a solution to the problem, write it down in the Mikado graph. Make sure that the precondition noted in the graph is not too extensive. It is better to divide extensive tasks into several steps. Make sure that the dependencies between the individual steps are shown correctly.
Discard all changes with the help of version control
This step of the Mikado method is very important: now discard all changes! This is the only way to ensure that you can carry out the next steps from a known state. If you continue working on the "broken code", you would very quickly lose the overview and get caught up in the chaos. This is exactly what the visualization in the Mikado Graph is designed to prevent. To do this, each individual step must be carried out on a code base that you know what state it is in. Otherwise, you are piling up a big pile of problems. Take another look at the image sequence in the first part of the article on. After you have applied a plaster, other problems appear immediately. You quickly lose track of things. You will then typically find yourself in one of the following two situations:
- You do not know whether your system is still working correctly. Your changes are translated, but due to a lack of sufficient automated tests, you do not know what state your system is in.
- You know that something has broken, but you don't know which change is responsible. So you have no choice but to undo all the changes.
Since you have already made a naive implementation with the aim of gaining knowledge, it is not a tragedy to discard all changes now. Let go of the code changes with a light heart and celebrate the knowledge gained.
Select the next precondition to work with
Now look around the Mikado graph and search for a precondition with which you can continue working in the next step. You will again try to implement this precondition naively. Of course, you will only select leaves because they do not depend on other preconditions. You are free to choose which leaf you want.
Conclusion
The Mikado method is a simple yet powerful method for complex refactorings. The challenge is not so much to understand the method, but to apply it consistently. The greatest difficulty is probably to stop in time when making naive changes, to note the realization as a precondition in the Mikado Graph and then to consistently apply a Revert in the version control. This takes practice. The Internet is full of practice material. Take a look at an open source project that you are using. Maybe you have an idea for an additional feature or discover a bug. This is a wonderful opportunity to practice the Mikado method.
The right seminar for this: Clean Code Developer Refactoring.