7 tips for dealing with an inherited codebase
What can you do if you’re faced with a codebase like spaghetti junction?
If comments are thin on the ground or the versioning system consists solely of files and folders labelled .old?
Taking on clients with existing websites is something we do regularly at CandidSky – whether they need a design makeover, additional website development, or if they’re in need of some SEO it’s usually quite a straightforward task getting to work on making the improvements. Every now and then however – us devs aren’t entirely prepared for what we encounter.
These pointers will give you a bit of help in getting to grips with inheriting a new codebase – whether you should make-do with what you’ve got, refactor, or take the plunge and go for a complete rewrite.
1. Have a thorough investigation period
It’s important when you first get to view the codebase to take your time to size it up. Ask yourself a few questions while going through the code:
- Is it well commented?
- Is it well structured?
- How legible is the code?
- Does it make sense?
The quality of the code that you’re going to be making changes to will have a direct relationship on how long it will take to complete new tasks once you start developing.
Going through bad, undocumented code can be very time consuming so it’s important that you give yourself enough time when estimating a job. Code that has little or no comments can be pretty treacherous to navigate and a good amount of time can be spent just making your own.
During this time try to document what you’re finding out as much as possible – there’s nothing worse than having to cover old ground because you haven’t taken notes.
Hopefully after spending a few hours with the code you can get a good feel for how long you think further development will take.
2. Set reasonable development targets
When setting development goals, it’s essential to focus on the biggest or most pressing issues first. If you feel that the codebase is particularly bad or there are inherent problems with it, it might be an idea to remove any enhancements or nice-to-haves from the development list entirely so that you can focus on getting the project to at least a stable condition.
If the codebase has no pressing issues, setting one or two smaller goals as proof-of-concept targets can be a great way to start. Give yourself plenty of time on these, using the occasion to improve your knowledge of how the system works and to make as many notes and comments as possible to help out with future tasks. Once these have been completed – you can use this development sprint as a yardstick for estimating the other jobs.
If, in your proof-of-concept sprint you start to come up against real barriers that mean even the simplest of tasks are taking too long or are even impossible – you’ll have to start asking yourself if the entire codebase needs to be reviewed or revised before any of changes can be attempted. At this point you might be a candidate for our ‘should we start again’ section below, but keep reading on in the meantime just to make sure.
3. Don’t be afraid to tell the client
If the codebase is going to cause you problems, don’t be afraid to tell the client. Telling the client early on in the project, although isn’t the best of news for them – puts them into the mindset that delays might be inevitable.
4. Have a plan and stick to it
You should now have a list of changes that the client is expecting and in order to maximise your efficiency in completing these tasks and to help to avoid some of the pitfalls associated with bad code – it’s usually wise to not try to do everything at once. Take on tasks one at a time – if you’re going to be flummoxed by the codebase – it’s best to be confused in one place at a time. Baby steps is the name of the game.
It’s often tempting when going through a codebase to make quick fixes and changes to bits of messy code as and when you see them. As enticing as this is, you can’t always be 100% sure that your changes won’t affect something else down the line and if the part you’re working on isn’t related to that area, it can take some considerable time before any problems that you might have caused start to manifest themselves.
The same rule applies for areas of code that you assume can’t possibly be needed so you can remove them without worry – DON’T! Not unless you’re absolutely certain it’s not in use. Your code editor or IDE’s search function can be pretty invaluable in this situation but not completely fool-proof – there may be variable variables at play, calling classes from strings or other such techniques that will often slip under the radar of ctrl-f.
5. Version control it
If the project is lacking a form of version control you really need to implement it straight away. Using version control allows you to keep track of changes (especially if you’re cavalier and decide against my no quick fixes rule!), it also allows several people to work on the code at once but stops things that can be already complicated getting way out of hand.
Versioning also lets you easily set up code reviews with fellow developers so that you can get several pairs of eyes on the codebase. This can help eliminate any potential bugs – they might notice something you haven’t or can shed light on a section you just can’t seem to fathom.
Ultimately, with version control, if the worst comes to the worst and one of your changes does break something you can always roll-back the commit, work out exactly what caused things to wrong and start again.
6. Test test test
A no-brainer really, of course you’ll be testing – but because of the sheer amount of unknowns that you can come across with someone else’s code you’ll need to ensure you test everything and test it thoroughly.
It’s a good idea to set up a parallel testing environment with the live site that is kept as up to date as possible. As you’ll be quite new to the site and won’t know all of its layouts and functionality at first glance of the pages – it will allow you to compare the two sites side by side to ensure that nothing strange is now happening and that the site is still fully functional.
7. Should we start again?
Although it might seem contradictory to start the project from scratch – it can sometimes be the best option – especially when there is to be continued development for the foreseeable future on the project. It’s a good idea to weigh up the time you think it will take for the rebuild vs. the amount of time, stress and potential problems that can occur trying to keep up a bad codebase. Use your judgement – with what you’ve got, can you manage what the client is expecting without compromising on the quality of work?
While it can seem like a simple decision to rebuild – convincing the client may be a pretty tough battle – especially if to all intents and purposes they have a working site. It’s usually good to explain how much quicker continued development will be, and the improved maintainability and stability of the site.
Remember to create a mirror of the original site when starting from scratch so that you and the client have an exact copy of the old site with which to compare the new. Its quite a predicament trying explain that something was already broken when you have no way to prove it.
Use it as a positive – learn from the code
Viewing other people’s code is a huge part of learning and keeping up your skills in programming. If you’ve inherited code, try to learn it inside out – you might see an interesting new technique, or a way of doing something you’d never thought of before, even if it is one of the nastier examples of codebase.
You can always strive to make your own code better; that bit more legible, variable names more descriptive or comments more informative.
Nobody sets out to write bad code, be patient, look for the gems and keep methodically working through the project to make it the best it can be.