As developers, we are expected to be able to dive deep and fast to unfamiliar code and it’s not easy, especially when there is no documentation and no “go-to” person around.

I encountered this situation when my entire group started working on an existing project which originally was developed by another business unit. There was no documentation, and we had minimal support from the team that created the project.

Another challenge was that most of my team members, including myself, were backend developers, whereas the new project required full-stack knowledge and experience.

After spending some time working on it, I can say that this was a great opportunity for me.

Now I want to share with you the approach I adopted to handle problems in a web application with an unfamiliar codebase.

First Things First

When running the application, and encountering unexpected behavior, I first want to identify if the source of such behavior is on the client or the server side.

To do so, I open the chrome developer tools (similar tools are available also for other browsers) and inspect two tabs: Console and Network.

In the Console tab, I search for errors and stack traces which will indicate that the problem is on the client-side.

In the Network tab, I review the API calls and their statuses. If all of them are ok (got HTTP status code 200), it’s another indication that the problem is on the client-side.

Client-Side

When I suspect that the problem is originated by the client side, I can launch the debugger from the Sources tab in the chrome developer tools. But how would I know in which file to begin the debug?

If I found the relevant error stack trace in the Console tab, it’s easy, since it would point me to the relevant line in the code.

Otherwise, I’ll need to identify suspicious API calls in the Network tab and search for them in the source code. In my organization, we use opengrok, which is a fast and usable source code search and cross-reference engine. But searching from the IDE is also an option in case all the source code loaded in the workspace.

Server-Side

In case I got an error from the API call (HTTP status code is different than 200), I’ll check if the problem is exposed in the API response.

For example, if the API returned an exception or error message that explains the problem, this would lead me to the exact place in the server-side code.

If this is not the case, I’ll have to examine the API design and implementation to understand which server logs may contain the relevant error stack trace.
Finally, if the root cause is still not clear, I need to add more printouts to the log or perform remote debugging.

A Few General Tips

• When debugging unfamiliar code, we don’t always know which files are involved in the specific feature. A good way to discover it is to look at the commit history and see which files were committed together with the file that implemented the API.
• Examining the recent commit history of a specific file may help to understand the flow and even reveal the source of the bug.

Epilogue

All beginnings are hard, especially when there is no one you can ask for help.
But it’s a great satisfaction once you are able to understand, maintain and enhance the existing code.

I hope you’ll find my approach useful. I will be more than happy to hear about your challenges, tips, and best practices while moving to a new project in the comments below.