Congrats: were migrating

Intro: the part you can skip…

The only hard-copy software book I own is “clean code” by Robert Martin. I keep it as a compass, a reference and to present it to other developers. But each time I talk about the book I knowledge that the reader might have one of two totally different experiences. It depends on if you are reading it as a junior, or as an experienced programmer. While the first will read it as “makes sense” book, the experienced will sometimes laugh and sometimes cry, saying over and over: “been there done that”.

This is why when I received an OK for migrating the APP, I felt the weight of the big responsibility within the task, recalling all the horror stories Robert mentioned in the book. To make it even harder, the reason I been hired in the first place was that the company got far behind schedule with the same sort of migration and the managers still live the trauma of the previous attempt.

Migration guideline and goals:

Since the migration of an app can be traumatic, it’s either doing it perfectly, or not at all. This is why even before starting the research, I wrote down the basic conditions, that without them we will not start the process.

Something you can sell

To migrate you need a good reason. And my needs are not always aligned with the company’s needs. So if I can’t explain and convince why I want to do it – I should not do it.

Measurable

Migration is a long process. If I can measure progress there is a big chance it will never end. And there are plenty of horror stories that can show how bad it can be.

Don’t support two systems simultaneously

While I have fun with the brand new code, the old app continues to change. The longer the migration takes, the bigger the chance it will be irrelevant. Sometimes the new app will be irrelevant even before it had been launched. There are times the current code changes, or I’ll end up supporting two different systems that will continue to live side by side.

Continues approach

The only way to avoid the previous section is by continuous approach. Replacing a small section of the app immediately after rewriting them. That way I have a small and measurable process, instead of one big task that can get out of hand.

Micro frontends approach

Micro-frontend is the best way to create a solid independent and testable app. Unfortunately, most of the time it’s unrealistic, or too complicated to be worth the effort. But still, the goal is to keep the isolated components approach. This will help the previous goal, of continues replacing the old components with one solid one.

Document behavior before refactoring

Over the years the APP changes and the documentation don’t hold up. Sometimes small changes that had been written somewhere else. And in my cases, plenty of the changes were done without a product manager, just a basic guideline and the developer had to fill the gaps.

Before a developer starts to refactor, he needs to prove to himself that he has a good understanding of what the current component does, understand what it affects, it’s dependencies, and define the component tests.

Documenting the app by tests

Rewriting is a good opportunity to create a clear description and understanding of the components. But since documentation never holds. Documenting the app behavior by writing component tests servers two important goals: creating a testing safety net, and having always up-to-date technical behavior documentation.

Separation of code from UI

There is nothing like good spaghetti code. And the fun of throwing new values all over. To make it even worse, have some NG components side by side with VUE while rewriting to React. This is why one of the goals was to have data objects that expose “computed” values for all the UI needs. If I have a graph, and I need to calculate it’s height, Ill do it outside the view. This will name the testing much more easy and solid, help organize and understand the component. And be helpful when we one day we will migrate from React to the new framework…

Coding standards

I hope this section needs no explanation. If something starts as a mess, It will end as chaos.

These are the goals I wrote down, presented while talking with the managers and displayed as expectations in front of the team. If you think that I missed something, please comment on it.

About the harder question, how I convinced the posttraumatic managers that it’s time to start a migration? That for some other time.