Doing maintenance work on a codebase isn’t very glamorous, and it isn’t always much fun, but it’s an important piece of building lasting software.
Everyone loves working on so-called greenfield projects because they can let their creativity run wild. Adding features and fixing bugs in a system that’s already been built doesn’t seem to generate the same enthusiasm, but it still requires a great deal of creativity and ingenuity.
If working on a greenfield system is like putting together a puzzle, maintaining an existing software system is like solving a riddle.
1. Get Time with an Original Team Member
Sitting down for half a day with someone who was around when the system was originally created can pay off dozens of times over. Ask questions, but also just try to stay relatively quiet and let them talk.
Pay attention to what areas of the code they gravitate to first. These are likely to be the most challenging areas that the original team spent a lot of time on. These areas might be complicated and appear overly abstract to a fresh mind without context, but try to get a sense for why they chose the abstractions they did.
Also, pay attention to the areas they’re proud of. If they solved a problem in a particularly interesting way, they’ll enjoy explaining it to you. Take notes on the high-level details, and ask questions to clarify your own understanding. Details like these will help immensely if you’re asked to solve a problem or add a feature that touches that part of the code. It will also make you aware of an area of the codebase where you might be able to exercise your own creativity to do something intellectually satisfying.
You should try to check in with this person as needed. After a week or so of solo work, you will probably have a huge list of questions. Sit down for another session, and things will be much clearer than they were originally. Continue doing this until you aren’t generating questions at the rate you were at the beginning.
2. Don’t Try to Fix Everything
If you’re the kind of person who sees something wrong and has to immediately try and fix it, try to resist that urge. It’s easy to fix small things, and you should, but if you ever want to throw out large chunks of code and rewrite them, think twice.
You have to remember that you’re working on a system that already works and provides value, and cleaning up the code might not be the best use of your time. If the code isn’t in active development, who are you really helping by rewriting it anyway? Also, are you positive you know enough about the system to be sure you aren’t breaking something somewhere else?
That’s not to say that a little refactoring is never a good idea, just pick your battles wisely and treat the code like a surgeon might treat a patient. Get in, fix what you need to fix, and leave everything else undisturbed.
3. Keep Notes for Yourself
Take notes as you go through the code, and save them for yourself. Don’t add them to the repo, and don’t add them as comment blocks in the source.
Adding your own second-hand opinion of what someone else’s code is doing is only going to confuse someone else down the road. Your notes might be full of more questions than answers, and that’s not good material to commit to the repo.
The longer you work on the project, the more of those questions you can answer, and the more valuable your notes will become when you have to context switch back into the project after an extended absence. If you are ever in the position of having to onboard anyone else, your personal notes can provide a starting point and give you examples of areas that should be covered.
4. Don’t Get Discouraged
Maintaining software is hard. Everyone has different ways of dealing with complexity, and the way the author may have chosen might not be exactly the way you would have chosen. Be comfortable with the fact that, at first, you won’t be nearly as productive as you’re used to. And try to strike a good balance between learning the system and getting work done.
A lot of time and effort goes into building a piece of software, and continuing to get value out of it long after its initial development is critical. If you find yourself needing to support a piece of software that you might not have much familiarity with, hopefully, these suggestions can help you make the most of the experience.