In my last few jobs, I’ve had the pleasure of coming into the company and taking partial responsibility for large, complex code bases. Often much of the code was written by someone who was no longer at the company. This can be a daunting task, and if you’re a software engineer, it’s a position in which you’ll mostly likely find yourself at some point in your career. I’d like to share some of the things I’ve learned—in convenient listicle form.
1. Don’t try to learn it all at once
For a small project, it might be appropriate to read through all the code files, but for something large and complex, trying to understand everything at once will be counterproductive. Focus on just one small unit at a time, gradually adding to your knowledge. Nobody’s expecting you to become an expert overnight (and if they are—maybe reconsider your employment).
2. Make sure you understand what the purpose of the codebase is
Before you dive into the code, and even before you start learning about the structure of it, take some time to learn as much as you can about how the software is supposed to work. If it’s UI-based, watch some users using it. Try using it yourself. Figure out how the software fits in to the larger business perspective.
3. Read the unit tests (if any)
Once you have a firm grasp on the bigger picture, it’s time to learn about the smaller pieces. If you’re lucky, there will be a substantial number of unit tests. If they’re written well, they’ll show you how the units of the software are expected to work. If there’s one thing I’ve learned in my experience, it’s that there are never enough comments in source code. I know I’m guilty of that myself. But a well-written unit test can be a form of self-documenting code.
Of course, in reality, there won’t be enough unit tests, they won’t be clear, and some of them might even be broken—but start there at any rate. And if there aren’t any at all? Then maybe you’ll have to write some yourself. Not only will you be making the code better (see tip no. 9), but you’ll be learning about how it all works.
4. Don’t be afraid to ask questions
If you’re confused about something, you’ll usually get a better understanding if you first try to figure it out on your own. Eventually, though, you’ll run into a problem you can’t tackle by yourself. That’s when it’s time to seek help. There should be at least one person at the company who’s familiar with the code. Even if it hurts your pride, asking for help is better than spending weeks trying to learn something that can be explained to you in half an hour.
5. Break it
The best way of learning how something works is to break it. Make changes to the code, then run it and see what happens. Don’t do it randomly, though—approach it like a scientist would. Make hypotheses and try to invalidate them.
6. Start with a project
A good way to focus yourself and implement these steps is to have a project to work on. Get input from others on the team, and pick a small project that touches only part of the codebase. Bug fixes are probably easier to start with than new features, because it won’t involve writing (much) new code. Once you finish that, move on to a different project that touches an entirely different part of the code. As you go on, you’ll start to see how all the pieces fit together.
7. Set breakpoints and debug
Once you have a project and an achievable goal, start debugging. Put breakpoints in the places you think are important, and follow the program through the code path. Good debugging is an entire topic in itself, so I won’t go much into it, but in my experience, it’s the best way to learn how something works.
8. Maintain style
A consistent style throughout a codebase can be hugely beneficial for readability and maintainability. If you’re lucky the code will already be consistent, and it will make it easier for you to learn. It’s your responsibility to maintain that style. Most style guidelines are just that—style. Unless you feel very strongly about something, go with whatever’s already present in the code. Your company might have their style guidelines written down somewhere, but if they don’t, you should still be able to pick it up from reading the code. IDEs often have automatic formatting that can be shared between users. If there isn’t already a repository of those settings, create one.
9. Make it better!
And finally, follow the old boy scout maxim of leaving your campsite better than the way you found it. As a newbie, you’re in a unique position to see the codebase from a fresh perspective. Someone who’s been around the same code for years will have adjusted to a certain way of thinking, and may not see better alternatives. Don’t assume that the way something is done is the way it has to be done. Question why it was done the way it was. Before long, you’ll be the hardened veteran doing things the way they were always done, so take the opportunity to look for alternatives while you still can.
Beyond that, add in comments and documentation for the places you had trouble learning. Write those missing unit tests. Make the style consistent. Do whatever you can to make it easier for the next person who comes along.