Vinicius Rocha

Working with a legacy code base

After many years working with legacy code bases, I decided to put together valuable lessons that I learned along the way.

  • Lesson 1: Respect the decision of those that came before you
  • Lesson 2: Don't change what is working
  • Lesson 3: Look for existing patterns
  • Lesson 4: Do what you were hired to do and do your best
  • Lesson 5: Tests are your ally

Lesson 1: Respect the decision of those that came before you

Try to understand that the choices that someone else took before you where taken in a different context, at a different time and with a different perspective that they probably have now. Maybe by that time, it was a promising thing for the future. Even if you don't understand the decision, and it has no documentation about it, try to respect that and make the best of it.

"All gave some, some gave all." Howard William Osterkamp

Lesson 2: Don't change what is working

It is tempting! You see an ugly sequence of if statements that would look much better on a switch. You see some explicit declaration when you could be implicit because, for you, it is more readable. Or maybe, you prefer to remove a redundant namespace, just because. If no one asked you to, don't do that. You are destroying history, and you have a significant chance of breaking something.

Lesson 3: Look for existing patterns

Forget what you prefer, look for what the other developers before you were already using. Sometimes, the project is not using the same naming convention everywhere. If that is the case, try looking for what is the pattern in the section that you are working on and stick to that. Having the same ugly pattern everywhere is much better than not having one at all. Stick with it, and you will make others people's lives much better.

Lesson 4: Do what you were hired to do and do your best

You shouldn't point out how bad you think the code is. If it is, the person that hired you already knows. If the person doesn't know, it is because it doesn't matter. You don't need to point out the mistakes that others did in the past. Do your best on the task that you were assigned to do. Remember that you are paid to deliver something with value. If the change that you want to make is just a personal preference, it is better to step out and let it be.

Lesson 5: Tests are your ally

Sometimes, old code bases can be huge, with lots of hidden dependencies! That means there could be a good chance that if you change something in one place, it will affect something elsewhere. Try to focus on how you can guarantee that you won't break anything after each release. Write automated tests and set up a continuous deployment environment in place to execute them. It will greatly mitigate the risk of making necessary changes or adding new code.


I didn't have anyone to give me those pieces of advice when I started working with legacy code. Because of that, I made my life miserable. I changed a lot of code that I shouldn't; I tried to use the naming convention that I believed was better; I broke a lot of things just because I wanted to make improvements that no one was asking me to. Don't make the same mistakes, work on what you were assigned to and look for the value that that will bring. Always respect the decisions taken by the other developers before you. An old code base holds valuable history and probably has tons of bug fixes that deserve your respect.