I was thrown into the codebase from day 1...

…I don’t really know how the system works… what do I do?!

Yup, I’ve been there too. My last couple posts talked about how much it sucks to be working with code that sucks. But what if you don’t really mind working with code that sucks, you just feel like you suck at working with it? Worse yet, you actually suck at working with it?

In a dream world, you get assigned to a legacy project and have as long as you need to ramp up to it. You write your first line of code only after achieving mastery with the code and its dependencies.

If you think about all the conditions to be met for this dream world, you’d realize it’s a fantasy. You might get a couple explanations from OG developers. You might have some outdated documentation. If you’re lucky, you might have a few tests.

You’re not going to feel 100% ready every time you sit down with the code. You won’t be able to give a perfect estimate to your boss. You’re not going to be happy with the technical debt that previous devs have left you with.

What do you need to know?

You can still be a badass and ship good code faster if you have a better strategy. The key is to focus on what you need to know.

If you’re like me, you want to know everything. You don’t feel right if you don’t know everything about the code you’re messing with. You read tech books front-to-back before giving yourself the permission to actually use the tech.

Michael Feathers, in his book Working Effectively with Legacy Code, dedicates a chapter to times when you “Don’t Understand the Code Well Enough to Change It.”

Feathers describes using the “Scratch Refactoring” technique and “Just get in there and start moving things around and making the code clearer.” He follows up with “The only problem is, if you don’t have tests, this can be pretty hazardous business.”

Instead of writing scratch refactorings, I say write scratch tests! Trying to write a test for sucky code usually needs refactoring just to get the first test to pass.

Instead of wasting your time doing scratch refactorings and then throwing away the “scratch,” write scratch tests to facilitate permanent refactorings. Throw away the tests if you don’t like them, but those refactorings can stay.

The message here, whether you scratch refactor or scratch test, is making sure you are focusing on understanding the right things. Feathers explains:

“Scratch refactoring is a good way to convince yourself that you understand the most important things about the code, and that, in itself, can make the work go easier. You feel reasonably confident that there isn’t something scary behind every corner - or, if there is, you’ll at least have some notice before you get there.”


When you’re faced with a huge legacy project, don’t try to understand the whole thing at once. Plan to make some precise, targeted refactorings facilitated by tests that focus your attention on what you need to know about the codebase. Use these tests to solidify your understanding of the code. Throw the tests away, or refactor them if you want to keep them.

Don’t forget to sign up for my newsletter to get posts about .NET, C#, testing, and architecture sent directly to your inbox!

Related Posts:

comments powered by Disqus