How to deal with necessary workarounds in software?

Question

Even with detailed specifications for exchanging data between computer programs, chances are that data generated by older versions of programs do not conform 100% to the specification, or that they use old obscure features which few people know how to implement them. As a result, companies have to keep a library of "odd specimens" for testing their software.

In good software design, these quirks can be confined into a small layer of libraries called "Abstraction Layer". However, most abstraction layers cut off too many functionalities (in order to prevent the higher level software from touching the unstable parts of the lower level software).

Sometimes it is not possible to completely hide away the unstable parts. What are the strategies for coping with such necessary workarounds?

((Please pardon my poor language skills.)

Answer 1

Good documentation.

Code comments go a long way towards telling the next developer why the hack was placed there, and why it needs to stay.

Hopefully the reason is sound. At some point, if enough technical debt is incurred, a refactoring should be considered.

Answer 2

Unit/integration tests can be used to identify those 'features' (if they can't be removed). Likewise, the same kinds of tests can test the code that consumes the libraries in question to ensure that they satisfy the contract of mis-behaviour.

Answer 3

If data files, consider creating a translator module or separate program that will do the translation for you into the new format. Embed the knowledge of old -> new formats in that module and keep your current code clean.

Answer 4

Sometimes it is not possible to completely hide away the unstable parts. What are the strategies for coping with such necessary workarounds?

It's important to realize that the software will keep evolving in the future. One layer of obscure workarounds is tolerable, but real problems will emerge if you start building workarounds on top of workarounds. Therefore refactoring is absolutely required before the layer of workarounds is going to exceed one. Of course it would be better to do it cleanly in the first place, but it simply doesn't go like that in the real world.