Tackling Legacy code - PHP developers

Call to Discuss Your Project subscribe to the blog rss feed

Leaving a legacy

Added Tuesday 11/11/2008

We've all been there haven't we? You're given a huge undocumented legacy code base and told that the client wants new features A and B added. I doubt there are many PHP developers out there that don't spend at least a certain amount of their work time maintaining or upgrading old code.

Even if you wrote the original code yourself a few years ago, the chances are you will have become a much better programmer during that time and will look at your previous efforts in disgust and think 'God, did I really write that? What a horrible way of solving a problem!' or 'Why on earth did I not write any documentation?'. Do not fear brave coder, here's are a few tips to make you and your colleagues lives a bit easier when it comes to the dreaded legacy maintenance.

1) Don't be daunted
It's very easy when looking at a large legacy code base for the first time to feel like any work on it is going to be an uphill struggle (especially if it's written in non-object oriented code). A lot of legacy code often looks a lot worse than it actually is and once you get your head around it you'll soon understand what the original developers were trying to achieve. If you plug away at it you'll soon get it. It's like those magic eye pictures ... you just have to look at them for long enough to see the sailboat.

2) Don't refactor everything
The temptation is always there when working on legacy code to refactor. Don't! If you've got to add a feature or make a change to old code then the likelihood is that the code is still working fine and people are using it. Sure, it might not be pretty OO code or follow that cool new design pattern you learned last week but if it's not broken, don't fix it. Save all your new ideas for new projects and don't introduce unnecessary bugs to already stable code. I often find the best approach is to follow the style that the code is written in, even if it differs quite significantly from your current way of coding.

3) Write some basic documentation as you go
If the code you are working on hasn't been documented, another member of your team is going to come along a few months after you and have exactly the same problems figuring out what's going on. Take some time to create some simple work flow diagrams with notes about which main classes each process uses. Writing proper documentation for these kind of projects is far too time consuming if all you need to do is add a few small features but adding some guidelines and notes will come in really handy for others (and yourself if you ever have to come back to the code at a later date).

4) Auto-generate Entity Relationship diagrams
There's nothing worse than trying to figure out how a database works by tracking keys across tables and writing SQL to gain an understanding of how everything ties together. Reverse engineering the database into an entity relationship diagram will automatically make it easier to understand. Most of the popular databases have either their own or 3rd party tools to create ER diagrams. Oracle has the Data Dictionary and 3rd party tools, open-source databases such as MySQL and Postgres have plenty of third party options to choose from and SQL Server has ER modelling built in. It's well worth documenting large databases and sticking them up on the wall near your desk for quick reference.

Hopefully in the future these issues will be less relevant due to the advances in the way PHP is written. Object orientated code, MVC Frameworks, PHPDoc, etc all help to keep the code cleaner and easier to maintain but for the time being a lot of us are still required to maintain legacy code and I'm sure will have to for a long time to come.

Happy coding!