Navigating through an undocumented codebase with little help (Rails Edition)

Target - junior developers

You'll sometimes find yourself having to work through a large codebase that doesn't have any documentation and probably has no test suite included. It could be on a freelance project or upon joining a new team. Your project owner needs you to start delivering immediately and you're the only developer he has. To help deal with scenarios like this, I'll be sharing some tips about how to best handle cases like this and deliver on your projects like you're expected to.

binding.pry

One of the first things I do when jumping on a project is to see if pry-rails is installed. An alternative would be to use byebug which ships by default with rails. I find the pry debugger to be much more easier to use. To those not familiar with either tool, they allow you place breakpoints at different points in your application that pauses execution of your program when they get there.

I'd normally place pry breakpoints at different locations in what I assume is the path to the request I want to work on and examine what happens at each point. pry and byebug allow you run your code directly in the terminal window so you can observe and outputs directly. For a codebase you're unfamiliar with, this could be of great help as it would help you determine how the application you're working on should behave if you're having issues understanding the code itself and also works as a good debugging tool.

Asking questions

Sometimes, you can get carried away and think you're some rockstar developer who can solve any problem that's thrown your way, only to spend days looking for what you're meant to work on when you could have spent just a few hours had you asked someone in time. This is trickier to do when you're the only one on the project and the project owner is non-technical. To get around this, avoid asking technical questions like which services or controllers you're meant to focus on for a particular task and instead ask questions about behavior. You'd be able to find things faster if you understand how the app should work even if it's from the end user's perspective than trying to figure it out on your own.

Going through old Pull Requests

One of the things I do to get more perspective on what I'm to work on when joining a new project is to go through old Pull Requests to see how previous developers on the project worked on tasks. This usually helps me understand what I'm meant to work on faster than going through most of the files in the codebase. The general idea would usually be to find PRs related to whatever task you're meant to work on and see the kind of work that went into it. They'd also give you an idea of the conventions that the previous developers on the project decided to follow.

Global search

Say you're asked to work on a bug fix that has to do with resolving a problem with your application's USSD implementation. Outside of going through PRs that focused on that, you can do a global search for terms related to what you're working on, like USSD in our example and see which occurrences come up for it. If none does, try something similar like mobile payments. With time, you'd be able to refine this skill and find what you're looking for on any project within a short period of time.

Looking at code from included gems

One of the things I started doing recently when trying to debug something on a project that I just joined is to take a look at code from included gems. This isn't something that you'd have to do often but if you're trying to understand a piece of functionality that comes from a gem, one of the best approaches to take would be to look at what's going on under the hood.

You can combine this with binding.pry and execute lines that you're interested in the method you're taking a look at. Remember to remove the breakpoints when you're done. Also, restart your server after making changes to files outside the scope of your project as the autoloading mechanism in Rails won't pick them up.

This isn't an exhaustive list of approaches to take but they tend to be my go to options for cases like this. One other thing I'd want to add would be to try to add tests if none were already there when you started the project. I find using tests to be a better approach to debugging code than relying on working with the application directly, and your future self would also be grateful to you for making that choice somewhere down the line.