Improving Legacy Code With Unit Testing

After Training a group of Embedded C programmers TDD, we usually have to deal with the fact that most their development work involves existing code. We have to go from the training environment and put the ideas in existing code. My Legacy Code Workshop is where we transition from the ideal training environment to the reality of adding tests to the code that is paying the bills. In the workshop, we get the test environments set up and write a single test case to prove the test runner is under our control (pass a test, fail a test). After that the fun begins. Embedded C/C++, with target HW and RTOS dependencies, can be very hard to drag into the test environment. Often people want to give up after about 15 minutes. Sorry, that is not an option if I am there. We choose a function to call, and start pulling the code into the test environment one build error at a time. We look at the first error, solve it, then continue. By focusing on only one error at a time, we find the natural order to solve the problem that "this code is not in the test environment". Usually, the code under test is not designed to be tested, and knows too much about the target system. So, build errors are expected and can be discouraging. Naturally, we first must track down header files dependencies, with an intermediate goal of compiling production code header file in the test case. Sometimes we also bump into vendor specific compiler problems, like non-standard header files for sizing datatypes and keywords that give access to hardware registers. Once the test case compiles, we celebrate. Then we add the production code to the test build. Now we get to chase compile problems again. Eventually we get to linker errors, another milestone to celebrate. With the code under test's linker errors, we must decide do we want the real depended upon code or a test-stubs. My legacy-build script makes the choice easy for C code. The script will plug each external dependency with an exploding-fake. An exploding-fake is a test-stub that announces the function's name and fails the test. Now we can run the code and guess what, it explodes on the first call to an exploding-fake. Decision time: should we add the real depended upon code, or make a better fake? On the first test's encounters with exploding-fakes, we keep the fake dumb, hard code a return value and let the test run. Eventually, the code builds and we have a test that is executing a path through the function we called. The main frustration in the process is dealing with compiler and linker problems. Once those are solved, we turn our attention to designing tests that force the code through one path at a time, making test-subs smarter as needed. That first test is expensive. The next tests are a lot cheaper. We consider the cost of adding that first test, the cost of doing business. It is a cost associated with the change we are about to make.

Sometimes, we have code that works but has problems. Maybe it is too complicated. Maybe it has methods that are too long and do too many things. Or maybe it is hard to read because things are named badly. In any of these cases, the answer is to refactor the code. Refactoring is defined as “restructuring existing source code to improve its design, structure, and implementation without changing its external behavior or functionality.” Usually, this involves making a series of small changes that gradually improve the code. Before you start any refactoring, you need to make sure you have unit tests that verify the external functionality you need to preserve. A broken test means you need to roll back the change and try again. If you don’t have adequate tests, write them before you start. What if you don’t have tests, and the code is so badly structured that you can’t write them? In that case, you can look at Michael Feathers’ great book, “Working Effectively With Legacy Code” (https://lnkd.in/gCSvihYP). Feathers defines legacy code as any code without unit tests. This book has a lot of techniques for relatively safe refactorings that get the code into a state where you can write tests. Refactoring steps don’t need to be huge. In fact, it is better if they are not. If you make a small change, it is easier to roll back if you break something. Then you can make the next small change. Very often, a refactoring step may seem to make the code woaxrse, but that is okay. It’s like rearranging the furniture in a room by moving one piece at a time. In the middle of the process, you might be able to sit in the chairs, but the room would look messy. Possibilities for useful refactorings are endless. Maybe you find a variable name that is confusing. Then you can improve things by renaming it. Perhaps you find a confusing method, and can break out part of it into a well-named smaller method. You might extract or inline a variable. At a larger scale, you might want to extract an interface or a superclass, or move a function from one class to another, or into its own class. I will try to delve into some of these more deeply. In the meantime, Martin Fowler’s “Refactoring: Improving the Design of Existing Code” is the seminal resource. (https://lnkd.in/gVe6tDFm).

Legacy code: it’s a mess. No one wants to touch it. But it pays the bills. You open a file and it’s like walking into a maze: → No comments. → 300-line functions. → Variable names like ‘temp3’ and ‘doSomething()’. It’s a nightmare. But here’s the reality: most of us don’t get to start fresh. The code works, and rewriting it isn’t practical. Your job? Make it better without breaking it. Here’s how you can approach it: 1. Understand before you refactor. Don’t just dive in and start deleting things. Read it. Map it out. Use tools to speed this up. Ex - Bito can summarize logic or explain what a function or entire files does in plain English. Saves hours. 2. Write tests first. If there are no tests, you’re flying blind. Write some coverage before you change anything, so you know if it breaks. 3. Fix small, high-leverage things. → Rename variables (’temp3’ → ’averageTemp’). → Split up massive functions. → Add comments where the logic is dense. Small changes compound over time. 4. Leave it better than you found it. If you struggled to figure something out, document it. Add a test. Refactor the worst parts. Legacy code is how we got here… it’s alive, it’s evolving. Don’t hate it. Maintain it. And when you’ve got the right tools, the process doesn’t have to be painful. I’ve seen teams clean up years of spaghetti with AI tools that: → Identify unclear code. → Suggest refactors. → Catch bugs early. The goal isn’t to “modernize” everything. It’s to make legacy code easier to extend, understand, and trust. Fix what matters. Move fast. Don’t break things. #bug #code #ai #developer

I hate legacy code. You hate legacy code. Even my grandma, your grandma,  And probably the guy who wrote it hates legacy code. But in tech, legacy code is like Delhi pollution. You can complain about it all day, but at some point, you still have to breathe and get work done. After 7+ years of dealing with old functions, mystery classes, and comments that lie straight to your face, here’s what I’ve learned about growing because of legacy code. 1. Let’s not judge and criticize. Most juniors jump straight to rewriting. Seniors slow down and observe. Legacy code usually exists because it works for some use case someone once cared about. Before touching anything, read the inputs, read the outputs, check for side effects. Example: If a function is doing five random things, map them out. Often you’ll see patterns that reveal why the original engineer wrote it in that shape. This habit builds your problem-understanding skills faster than writing new code. 2. Improve behavior before improving beauty Your goal isn’t to “clean up code” but to avoid breaking the universe. Wrap the code in tests, snapshot the current behavior, then refactor. It gives you a safety net and makes you fearless. Example: I once had to touch a 900-line Python script that sent out billing emails. I didn’t touch a single line until I added a couple of input/output tests. Those tests caught three hidden issues before I even started refactoring. 3. Document what the original developers never did Legacy code forces you to become the historian the team desperately needed. Every time you understand something, write it down in simple language. This doesn’t just help others. It sharpens your own clarity and pushes you into a leadership role. Example: Create a short “What this module actually does” note. Not a full wiki, just a clear 10–15 line explanation. People will start coming to you for context. 4. Break big tangled code noodles into small, understandable units Legacy code often feels impossible because you look at it as a giant mess. Instead, Split logic into tiny blocks. Name them clearly. Move repeated parts out. Make the code readable even if it’s still old. Example: Pull one section into its own function. Just one. Next time you touch the file, pull out another. Over months, the entire module transforms. Small changes scale. 5. Treat legacy code as leadership training Legacy code teaches empathy. It teaches patience. And it teaches you how to guide others through mess. If you can explain a messy system clearly, you’re already operating at a senior level. Example: Teach a junior how a legacy module works. Walk them through it step by step. That’s how you grow from “someone who fixes code” into “someone who builds engineers.” If you can handle legacy code calmly, you can handle anything. It’s not glamorous, but it builds the skill set most engineers only learn the hard way.