Within the past few months, I started developing an interest in detective fiction. I’m not entirely sure how it started, given that the genre never much appealed to me before, but I’ve been watching murder mysteries, reading Agatha Christie, and playing a Sherlock Holmes board game. My capstone group is doing an industry partner project which entails the need to interact with an existing codebase. This experience is a challenging, yet welcome, departure from the majority of my computer science education in which assignments consist of building a new project. It is often difficult to tell what one is looking at when browsing through the files of a project someone else has made. How do these parts interact? What does this function do? To further complicate matters, a large portion of the codebase is in C#, a language I have not used before, and we did not receive helpful documentation (…or did we? Stay tuned for the twist ending at the end of the tale I will tell! You’ll never guess the dastardly culprit!). To understand what was going on, I needed to put my sleuthing skills to work. Here are some methods that I used to solve the mysteries of the existing codebase.
Photo by Agence Olloweb on Unsplash
Start With What You Understand
Part of the codebase we were tasked with analyzing was a web app with a backend written in C# using the ASP.NET framework and a frontend written in Javascript using the React framework. Directly approaching the backend code left me confused because I am a C# amateur, but luckily there was a roundabout way of understanding what the backend was doing. Because the frontend uses the backend’s API endpoints, we were able to discover what sorts of endpoints the backend has by looking at the frontend code. We could deduce what sorts of HTTP requests the backend receives and the shape of the objects they return simply by looking at the frontend code.
I happen to be far more comfortable with Javascript and React than C#, so by starting with the frontend, I was able to gain insight into the mysterious backend. By using the insights I gained about the backend solely by examining the frontend, I was able to parse the actual code on the backend better. It is far easier to understand how a piece of code achieves what it does once you know what it does!
Eavesdrop
One useful tool for gathering information about what an API does given a functioning frontend is the “Network” tab in a web browser. In Chrome, this tool can be accessed by pressing F12 and clicking “Network” on the resulting interface.
When the client application sends a HTTP request to the server, the “Network” tab displays the details of the request and the response! Here is an example from a personal project of mine:
For any request our client makes, we can examine the URL, headers, body, and response! This is an immensely powerful tool that helps us understand the workings of the API.
Learn the Language
Examining the client side application helped me build a framework for approaching the server application. But getting a roundabout understanding is only scaffolding for approaching the actual code head-on. To do so, I needed to improve my understanding of C# and the ASP.NET framework. Microsoft has great ASP.NET documentation, and two of my favorite resources for learning a new programming language are Exercism and Learn X in Y Minutes.
Exercism enables learners to gain familiarity with the workings of a language by tasking them with completing small, approachable problems. I found this method of practice incredibly helpful when learning some Haskell, but because I’m already familiar with C++ and Java, I only really needed to understand the minor syntactic differences that come with C#.
Learn X in Y Minutes is a more appropriate resource when one already has some base familiarity with the general syntax of a language. It provides a brief but potent rundown of the major idiosyncrasies of a language, which was exactly what I needed.
Follow the Clues
One final tool I utilized to great extent was the Visual Studio right-click menu. Often when examining an existing codebase, you will run across functions and classes that you have no understanding of. They’re in the project somehow, but what are they? How do they work? Where exactly in the project are they? The Visual Studio right-click menu allows us to answer these questions.
We can right-click on an unfamiliar function call and click “Go to Definition.” Visual Studio will then take us to the exact line of the file in which the function is defined! This tool helps us piece together the structure of the project. Instead of an unformed blob of files, we can start viewing the project as a series of interlinking parts. This is one of the first steps down the road to understanding.
Conclusion
With the tools I described above, I was able to gain a decent understanding of the codebase I had been tasked with investigating. The mysteries fell away, but one remained–why was there no project documentation? A greater detective than I (one of my teammates) solved this mystery:
We had been emailed project documentation. It went to our spam folders.
Because our project sponsor’s email is not an Oregon State email and the message contained an attachment, the message was flagged as spam by all of our emails. The documentation ended up being helpful for understanding some remaining questions I had about the codebase, but it would have been far more helpful if we had been aware of it when we received it. However, I believe it was a worthwhile learning experience to work through the code as a mystery.
Leave a Reply