Ease out transitions
Most software design out there is a matter of personal taste. There are very few widely agreed upon rules. It happened to all of us. You get to read a particularly bad piece of code and think it requires a complete rewrite. In most cases, it wouldn’t be hard to get people to agree with you. Rewriting would make everything more beautiful and allow easier modification. However, it has a terrible cost. It will always take longer than you expected. Bad code has this ability to hide features inside. While it may happen that some portions of code are dead, most of the time, they serve a very specific purpose your great new design wouldn’t have considered.
Major backend rewrites also tend to leave the front-end part behind. It will break user experience. All the polishing that was made on the interface is likely to be gone because it was not re-implemented or simply left broken. It would probably take months to reach the same level of external quality (compared to days or weeks to improve the internal quality).
When you are at point A and think it’s not the best place to be, there is nothing wrong with trying to go to point B. However, teleportation does not exist in the world will live in, and your app won’t just appear in point B on the next day. Even if you rewrite everything, get a perfect backend and a better front-end. All this legacy data won’t just transfer itself. Data conversions are a pain. One of the reason the code was so bad in the first place is probably because the data model was messed up. Converting data for all the edge conditions is a very long process and is always prone to break, which leads to users complaining. Of course, this implies that your upgrade process even has a way to handle data conversions as part of the regular upgrade process.
Before thinking about your grand new design, think about transition. It will probably expense more effort than the development efforts. After you rewrote everything, will you be able to make it from A to B?
Recently, I started working on restructuring the wiki plugin API in Tikiwiki. The plugins are great. They allow to find the different features in the wiki and create create applicative wikis. The problem is that they are hard to use. The best ones have too many parameters and not all of them are really well documented in the UI (while sometimes documentation is better on the doc site). When too many parameters are used, it just becomes unreadable. I decided to rework these during TikiFestStrasbourg after all of us learnt one new thing about plugin capabilities during discussions.
These were some of the issues:
- Documentation in UI was a short blob of text containing HTML. It was not meaningful to users and a pain for translators to manage. Parameters were rarely detailed.
- Plugin list was not filtered. All plugins were listed, even if related features were turned off. This created too much noise.
- The syntax was hard to understand and a user interface would help a lot.
- Caching does not behave nicely with some plug-ins.
To solve these issues, more meta-data is required about the plugins. The naive solution is to rewrite the plugin API entirely and make it good. After all, at this time, each plug-in is stored in a separate file containing two functions with a naming conventions. This is not a modern GoF-endorsed design!
Well, rewriting is a bad idea. Tikiwiki ships with around 75 plugins, plus a few in a separate folder to be enabled by sys-admins in controlled environments, plus an unknown amount in mods, and all those custom plugins written for specific applications we have no control on. If we only had to consider our own work, it would still take around 40 hours to convert them all, considering no clean-up is made and documentation is only entered as-is without improvements. Rewriting the API would be a 3-4 hour job at most. The conversion is uncertain the result would break upgrades on all customized installations.
I’d much rather compromise a little bit on beauty to save some pain. Adding an extra function to provide all the meta-data and making sure that the functions who use these act conditionally based on if the new way of doing things is available. I can keep working on improvements without having to convert everything at once. No functionality is broken.
Of course, the transition still has to be made, but at least it provides us with more time to do it. No one will scream that their favorite plugin is broken. I will be able to merge back in trunk much faster and get help from the rest of the community.
There is more than just code involved.