How to Get a Running Start on a Legacy Project


… and Plant the Seeds for Organizational Change

I’m on a contract that may start winding down in a couple of months1, and so I’m starting to both look backwards and forwards to think about what I’ve learned and what I can do better.businessman_with_the_notebook_1 One of the ways that I think I can do better is to change my attitude toward taking on legacy projects.

In the past, I’ve always been fairly picky about my assignments — I choose assignments which will stretch me as a developer. I also use the interview as an opportunity for me to scope out the employer to see if there are any organizational or development process dysfunctionality that will keep me from doing my job effectively. As a result, I usually shy away from legacy projects.

But I’ve grown more confident in my ability to effect change in an organization, and so here are my list of things to do for getting off to a quick start on a legacy project.

Work the Way You Want to from Day One

… even if you haven’t convinced everyone that your way is the right way way

Coming onto a new project, you can’t always work the way you want to. There are legacy anti-patterns you just have to follow if you want to keep your job, and it doesn’t do you any good to be the new guy who’s always complaining. But the good news is you can just add your best practices on top of the bad ones you have to follow….

Use source control

If source control is not already in use, you can start by using source control locally without having to overcome the team or management’s resistance. I recommend Git, but Mercurial and Subversion are good alternatives.

Use a continuous build tool

If there is no continuous build tool already in use, install one locally. Even if there is a tool already in place, it may be a good idea to install one locally to monitor the code base and to keep a record of trends in code quality. I recommend Jenkins. Note that it’s okay if the project doesn’t actually have an automated build, as there are lots of uses locally for a continuous build tool.

Use static checkers and linters

There are quite a large number of open source/free linter/checkers out there for each technology. For example, you can use PMD or FindBugs for java code, jshint for JavaScript, csslint for css, liquibase for the database, and xmllint for xml. I usually turn off all the optional rules to start with so I don’t get overwhelmed, and then gradually turn on more rules as the code base gets cleaner.

Hook the checkers/linters up to commit triggers (or your IDE)

Whether in your local or team source control, add commit triggers to run the validation on the changed files with an override option to commit even if not all validation passes. The reason to run it just on the changed files is to make sure that you don’t get overwhelmed with issues in the existing code base. Your objective should be just to make sure hat you’re not adding to the problem and that you clean up the files you touch (when reasonable). The reason for the override option is that you don’t want to have to clean up a 10000 line file when you’ve only touched one line of code. I use Ant as my automation tool to run the checker, as it has a handy <changed> tag that can identify files which changed and run the checkers only on those changed files. Using Ant, I have a choice of hooking up to either my commit triggers or to the Eclipse IDE, which has convenient hooks for Ant. Alternatives: perl, shell, powershell, ruby, python, etc.

Hook the checkers/linters up to a trend monitor

I use the Violations plugin for Jenkins which plots trends in the number of violations in the code base. The Violations plugin recognizes a number of linter output formats, but can incorporate other checkers/linters if they output in the defacto standard of junit xml report output. Doing this integrates the checkers/linters it into your development process in a way that you don’t have to spend any of time actively monitoring it. Violations has thresholds you can set to alert you if the number of new issues grows beyond a certain point.

Create local repos for unit tests, performance tests, and metrics

If the legacy project doesn’t have automated tests and you want to introduce unit testing or other kinds of testing, create a local repository for your tests and add that to your continuous build.

Automate the setup

With packaging tools like chocolatey or nuget on windows, or apt-get or yum on *nix, you can script the installation of the tools above. This is both so you remember what you did and can do it faster in the future, but also to help you evangelize to other developers as well as management. A script makes setting up the best practice infrastructure much much easier. Make sure you save the script to your personal Github account2.

You’re ready to go!

All these steps should take about 2 days. It’s a small price to pay to get yourself ready to start coding on a legacy project the way that you like to code. If you have a previous scripted install already on Github, it should take you less than a day.

Now that you’ve increased your personal productivity, what about the team’s? It’s not much fun to be the only/lonely coder following a set of best practices. What you really want to do is to persuade your team members and management to adopt your coding practices as better coding practices. In order to do that, you have to …

Be an Agent of Change

office_1There are a couple of principles you need to keep in mind to become an effective persuader when you’re the newbie on the team.

Start locally and lead by example

If you haven’t noticed, all of the steps I’ve advocated above are ones you can implement on your own machine without having to get management or the team’s approval. This way, you’re making yourself productive without disturbing other people’s routines. If others are interested, let them come to you on their own initiative and ask questions. This style of persuasion fits well if you’re a low-key guy like me. Some people can carry off the role of the opinionated high-priced consultant, but I’m not one of those people.

Script everything you can

Anyone can script the installation using the packaging tools mentioned before. If you’re a good scripter, you should also script the configuration. This is lowering the barrier to adoption, a very important part of the sell. Once others are interested and asking questions, they’ll want to try it out for themselves, and when you hand them a few scripts that makes trying things out easy, well then you’ve almost sealed the deal.

Prepare your elevator pitches ahead of time, one for devs and one for management

Always be ready to be asked why the team should adopt your best practices. The success of adopting new practices is highly dependent on buy-in from both management and the developers. The devs will want to know the technical reasons and the management will want to know the business reasons. These pitches aren’t going to have much in common so make sure you keep the audience’s needs and desires in mind. One of the worst mistakes to make is to use geek-speak with your business pitch, so keep the language as simple as you can.

That’s it! Good luck on your next legacy project!


1 While I feel there is a high possibility that the contract will be extended, I learned from my first contracting gig to never take things for granted. I had been two months into a three-month contract working at a Utah startup, and my recruiter told me that the clients were happy with my work and saying they were interested in extending me, but nothing happened. Then, a week later, the bosses called all the contractors into the office, apologized slightly, and told us that because the startup’s clients had been late in paying their bills, they had to let all the contractors go, and would they please pack up their stuff and leave by noon.

2I haven’t gotten around to doing this yet or else I’d include a link, so please do as I say, not as I do.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s