Quick note: I'm creating a brand new community for developers focusing on building programming skills through a welcoming online collaboration environment. We need developers like you so consider joining us!
Is a member of your team leaving? Legacy code being handed down to you? Switching teams? These are just some of the reasons why developers can be faced with the task of maintaining code written by someone else.
There are many challenges that come with maintaining code you’ve had no involvement with up till that point. You may be handed over a bunch of code for a technology you might not be familiar with that requires enhancement. Or there may be an urgency to fix a bug discovered with an old code base.
To better handle such a task, it’s important for every developer to be aware of the challenges and have a systematic way of tackling it.
If you work as a developer you’ve more than likely been faced with this situation. If this isn’t something you’ve had to deal with yet, trust me, it’s only a matter of time!
Let’s go through some tips that will be useful for developers faced with the task of maintaining code written by someone else.
1. Do a handover session with the developer
If you still have contact with the person who originally wrote the code, do a handover session. Or two! Maybe three?
Use these handover sessions as a way to speed up the process of becoming familiar with the code base. Rather than the slower process of having to piece it all together yourself. The developer can talk you through the flow of the code and also point out any hidden ‘secrets’ or ‘hacks’ that might be in the code implementation.
Before the handover session, make sure you’ve at least reviewed the code yourself so you can note any questions you have. And during the session, make sure to ask your questions or any other that come up as they go through the code. And of course take notes during these sessions.
A handover session with the original developer is probably the fastest way to get to get familiar with a code base that’s new to you.
So if you still have access to the developer, make sure you reach out to them. If it’s a colleague about to leave the company, make sure you grab them for a few sessions before they leave and make this a priority for yourself. Again, do this before they leave.
There are other situations when a walk through of a code base is useful. If for example, you’ve just moved teams and are getting to grips on the code base, it’s vital you at least get someone to talk you through the basics of the code structure to speed up your familiarity with it.
2. Read all available documentation
These are all available documents relevant to the project in which the code was written for.
Project specifications? Software specifications? README files? Read them all.
Taking the time to read these documents will save you time in the future.
Rather than spending unimaginable lengths of time trying to figure out why the code was implemented in a certain way, your question may be answered simply by reading the README. Rather than trying to understand the purpose of sections of code by yourself, it may all be nicely explained in the software specifications.
Reading important documents still applies even if you’ve done a handover session with the developer who wrote the code. Documents exist for a reason and its unlikely they will have covered everything in your handover sessions.
Reading through documentation is especially important for legacy software with absolutely no access to the original developer(s). With no possibility for a handover session, all you have is the source code and any available documentation.
Final piece of advice on this tip, remember that README files are called README for a reason! (I’ve been caught out with this a few times..)
3. Run and use the software
This means to actually run the application as it was intended, and to use it as it was intended. This is so you actually know what the application does.
This might seem like an obvious point to make but such things aren’t always obvious to everyone or just ignored in practice.
A big mistake developers may make is just assuming they know what the application does by reading the code or from their vague understanding of the product. Make sure you run the application and use it like an end user. By doing this you’ll gain an overview of what the application actually does, learn of its features and its limitations. The process of trying the understand the code should become easier after doing this.
This also applies for software applications that may be written for specific hardware or platforms. Make sure to get access to whatever you need and run the application on the intended platforms.
If you’re trying to fix a bug, running the code should be an obvious first step in the debugging process, but again, it has to be mentioned!
4. Test, test, test!!
The title speaks for itself.
When you’re dealing with an unfamiliar code base, make sure tests exist to check it works before you make any major changes. Tests will help confirm things aren’t broken after you make your changes.
More than the challenge of just getting familiar with a new code base is perhaps making changes without breaking anything!
And assuming the whole point of you being handed over the code is to make enhancements or bug fixes, having tests is critical.
If tests don’t exist, make an effort to write a set of tests for the application. Whether unit tests, smoke tests, or any form of manual or automated tests. Having some testing in place usually works out better than having none.
Admittedly this is one piece of advice I need to take better heed of myself!
5. Embrace the challenge
When faced with the task of maintaining an unfamiliar code base, it may help to just embrace the challenge. And from overcoming this challenge, it will surely bring some benefits to the enhancement of your own skills.
First, you’ll develop your skills of reading and interpreting code not written by you. This will allow you to more naturally be able to pick up on a developers intention when reading code. Through practice, you’ll be able to tackle code maintenance tasks more easily.
Second, by maintaining code that’s originally not your own, you can pick up very useful techniques and practices that will improve how you write your own code. Reading code by another developer can act as a way of indirectly learning from them. Just be careful to only pick up techniques that are good practices and avoid the not so good ones!
Knowing that you’ll ultimately benefit from the experience should act as a motivation. So don’t be intimidated and embrace the challenge you’ve been faced with!
Conclusion
Maintaining code written by someone else certainly has its many challenges. But it’s just another part of being a developer and something we’ll all have to deal with at some point.
You’ll surely be better equipped by following some of the tips listed in this article and developing your own systematic methods when tackling an unfamiliar code base.
Have you been faced with the task of taking over code written by someone else? Share your own experiences and tips in the comments.
If you enjoyed reading this check out more posts on developer tips and coding productivity on my blog :)
Top comments (3)
Nice post! I also noticed you're an embedded C engineer. I've heard that a few times before, but I'm not sure what that means. What does your job require you to do?
Thanks!
So embedded programmers typically work on writing software for hardware platforms such as microcontrollers using low-level languages like C. You may have heard the term "Firmware" which is used to describe software that runs at a low-level. For example, the software running on your mouse, alarm clock, router, smart plug, electronics in your car, would all be called "Firmware".
Embedded programmers are distinct from traditional software developers because of the low-level nature of the application. This comes with a set of challenges compared to higher-level software.
If you're concerned about the underlying hardware and overcoming factors such as memory constraints, performance, power consumption, then this is Embedded programming.
If you want to learn more you can check out this post I wrote on my blog that introduces Embedded programming. In the future I also plan on writing posts here on dev on this topic. Feel free to ask any more questions if you have any!
Neat! I also never knew that something like MISRA existed, that's really interesting. Thanks for sharing!