When starting a new job or on to a new project you will rarely be working on a completely greenfield codebase. Getting to grips with unfamiliar code is a difficult process and the amount of new information to take in can feel overwhelming. Coming to Nestoria from a Ruby background this was doubly so for me, I was not only learning a new codebase but also learning Perl at the same time. Here are seven strategies that I used to get productive as quickly as possible.

Be humble

Humility might not be the first thing you think of when it comes to programming. After all hubris is one of the Three Virtues of a Great Programmer. However when confronted with unfamiliar legacy code you are likely to get demoralised by how often you come across things you don’t understand and the number of mistakes you make. Humility is required to accept this and just get stuck in. Sometimes you will not understand a piece of code because it is hacky and badly written and sometimes you will not understand it because you are not familiar with the domain, or simply because the underlying algorithm is inherently complex. Mistaking the latter for the former can waste a lot of time and will probably annoy your coworkers as well! Have the humility to assume that the original developer knew what they were doing and wait until you really understand something before being too critical or making significant changes.

Test first

If your codebase is perfectly covered with unit and integration tests then you probably don’t need this guide. However most likely there are areas of the code that could do with better test coverage, or more reliable tests. By adding or improving tests you can improve the reliability of the code base without the risk of breaking production code. Writing or rewriting tests forces you to really understand code in a way that is not possible when just reading it. Whatever you will be working on next, first spend some time reading the tests and then adding new tests where you see gaps. It might be boring but it will help a lot when you start writing production code. A good resource on how to work with unfamiliar code in this way is Therapeutic Refactoring by Katrina Owen.

Make something

As soon as possible get started shipping code. There is nothing that will get you familiar with the code quicker than working on it. Perhaps start with a small project and don’t worry too much about how long it takes to complete, concentrating just as much on learning as on completing the task at hand.

Ask questions

You could struggle along trying to work everything out for yourself but you will get up to speed much quicker by simply asking questions. Try to do a little research first, but asking dumb questions is better than struggling unnecessarily. The rest of the team can help by being open to questions and responding promptly. Even if a coworker’s question seems trivial, or you are not sure of the answer, new team members are more likely to ask questions if you respond to them in an encouraging way. It might be frustrating to be interrupted but getting new team members up to speed quickly is beneficial for everyone in the long term. If you adopt a RTFM culture in your team, people are more likely to struggle in silence, when a simple question could have saved them hours of work.

Pair with someone

Even better than asking questions is to pair with someone who is already familiar with the code. You get instant feedback and will pick up the numerous conventions that can be hard to pickup just from reading code. This requires discipline to be effective and experienced team members have to make sure they don’t end up just taking over. This is particularly useful for areas that you are completely unfamiliar with. For example I didn’t know very much about Linux sysadmin, so when doing tasks that required Linux knowledge other team members would sit with me as I completed them. Code reviews can also provide useful feedback.

Write the docs

Once you have some experience with the code start writing documentation when you feel it is needed. At first do this just for yourself, perhaps in a personal wiki page or even just in a text file. Other forms of documentation like creating and answering StackOverflow questions and then linking back in your documentation can also be useful. Once you start to feel sure your documentation is correct and would be useful to others then start adding it to the code and/or official documentation.

Zoom out

Right at the beginning, it is beneficial to get a high level overview of the architecture of your system. Get someone to draw and explain a diagram of the architecture of the new system you will be working on and then try to map the different modules in the code to the diagram yourself.

After a few months you will probably start to feel quite comfortable in your new codebase. You might only have touched a fraction of it, but you understand the conventions that the team uses and where all the most important pieces are. Now is the time to zoom out again and think about whether the architecture makes sense. How might you have done it differently and how can you use your previous experience to improve it? Is the architecture as explained to you in the beginning actually how the code works in your experience, how would you explain it differently?

I’m sure there are many other tactics to help get to know a code base, but these are the ones that have helped me the most. Let us know about yours in the comments.

Samuel Scully