Happy Bear Software

How we start work on a Rails codebase

As a web development consultancy, we look at a lot of Rails codebases. So that we can be efficient and productive on client projects, we've each come up with our own way to get up to speed and start delivering value. This week we asked the team What are your first steps when looking at a new codebase?.


Esther Olatunde, Senior Developer

When looking at a new codebase, the first thing I look out for is the docs for getting set up. If none exists, I ping the contact person to find out how to get set up. It’s important to always document what worked/didn’t work for me while getting setup because sometimes, even on a repo with documentation, the original developer(s) may have missed documenting a key component because they were writing the doc with loads of context/packages that a developer new to the codebase might not have. Setting up can sometimes take forever, this is one of the reasons why I appreciate the concept of automating your development environment for a codebase as it gets complex beyond a simple Rails app setup. If I’m feeling generous, I’ll update the readme with how I got set up. Actually, updating the readme is good practice, but I sometimes forget to do this.

Once my development environment is set up to run the code, I’ll run the tests. If all is well on my development and test environment, I like digging in to figure out what the major user journeys/flows for the application are. I will schedule a video call with the client to figure this out if they aren't obvious from navigating around. Knowing these helps me in 2 ways:

1) This helps me quickly get my local environment to match production as close as possible from CRUD-ing/manipulating items on the app (an added benefit is I get to catch as many bugs as I can from using the app as a real user would).


2) It also helps me to compartmentalize the models, relationships, controllers, views, services, etc and how things fit together in my mind which is super important for me. I take lots of notes at this stage.

If there’s a backlog, my preferred next step is usually to pick a teeny-weeny task and get that done just to dive in and get my feet wet.


Najaf Ali, Founder

When looking at a new codebase my goal is primarily to get productive fast. To do this requires preparation outside of looking just at the codebase. I need to know as much about the context of the code as possible, including what the business case is for it to exist, when the project started, what the big challenges are now, and what the owner of the codebase is trying to achieve. When I go to start making changes, I ideally want to know about one or two small improvements I can make to do a first pass through the development process.

When I clone the codebase and am trying to get my bearings, I’ll usually start by reading at any available documentation. I’ll then want to look at the Gemfile to see what familiar gems the application uses. I spend a lot of time looking at schema.rb to figure out the data model. For a particularly complex model I’ll scribble out an ERD by hand to help me make sense of it. I’ll look at routes.rb and see how that marries up with schema.rb. I’ll look at a random sample of files in the test/ or spec/ directory to see if they actually contain tests.

After this first look through the code, my goal is then to get the application running in development to the point where I can click around and use the application like a user would. This usually takes an hour or two at least. To make this easier for the next Happy Bear developer to look at the code, we try to update the documentation so that set up is easier next time.

Once I have the application working, the next goal is to try to get any existing tests running and passing. At this stage we’re just about ready to start developing, so this is where I’d start working on a small task to walk through the development process. For this I’d cut a new branch, make the change, issue a pull-request, and then pester who is in charge of the project to let me deploy it to production.


Kaitlyn Tierney, Apprentice Developer

Whenever I start working with a new codebase, I start with the readme and any other project-specific documentation. As I work through the set-up instructions, if I notice any anomalies that aren't documented, I'll usually open a pull request with any additional information or corrections that might be useful to the next developer.

Once everything is installed, I'll make sure the tests are all passing, then run the application locally and poke around, walking myself through the various user journeys. For Rails applications, there are a few places I look at straight away, just to get a sense of how things are put together. I like to read through the db/schema.rb at this stage, to get an idea of how the database is set up and what's being indexed. Next, I'll look through the Gemfile, doing a quick Google to get a high-level sense of the purpose for any dependencies I'm unfamiliar with. I read through the config/routes.rb to see the different namespaces and resources available, then navigate through some of those paths in my locally running application to make sure everything looks as I expect.

Then, I dig a bit further into the code. If there are feature specs, I'll look through them briefly to see what's being tested. Sometimes I have a look to see if there's anything interesting in initializers/. I'll also usually take a look at a handful of recently merged pull requests on the project, to get an idea of how the team handles code review and what their practices are for committing/squashing/rebasing during that process.


Gabriel Hilal, Senior Developer

Starting on a new codebase is always exciting and at the same time challenging. It's good to work on a different project from time to time, but sometimes it can be difficult to know where to start looking to get familiar with the codebase.

I usually go through the readme file, expecting to find some useful information about the project and the setup steps. Although the readme is not always up-to-date, it's a good place to start. My first goal is to install the needed dependencies and make sure the tests are all passing.

Once I have the application up and running locally, I like to generate an entity-relationship diagram to visualise the business domain. This type of diagram helps me to understand the associations between models and how the data are organised. Then, I go through the Gemfile, hoping to find just a few lines of code. For each gem that I'm unfamiliar with, I take a quick look at its documentation to be aware of the code that is loaded into the application. Finally, I look at the routes file to check the available endpoints. This file helps me to visualise namespaces and all points of interaction between users and the application.

Once I have a good understanding of the system architecture, I check the seeds file and any rake tasks that might be needed to populate my local database. If there are no scripts, I usually create one. That's a great opportunity to commit the first contribution to the codebase by improving the readme and any needed scripts to help other developers with the setup process.


Dorothy Wingrove, Senior Developer

Often I find it isn't until I start working on my first task that I get a really clear visualisation of a codebase. However there are some things I do that help speed this process up and allow me to begin delving in.

My first step when delving into a new codebase is going through the readme. Assuming there are some set up instructions, I follow those with the aim to get the codebase up and running. As I find errors, as there so often inevitably are, I use them to open up an initial PR. In doing that I find it is a good opportunity to go through the PR and deployment process in place.

My second step is to run the tests (assuming there are any) and get them working if there are failures. Looking at the tests, especially feature tests, can give an idea as to the key user experiences and journeys of the platform.

My third step is to open up the app in the browser (assuming step one went well) and to have a quick click around. If there is a seeds file I will run that in order to get local as close to the experience of production as possible and to hopefully create a user to log in with.

My fourth step is looking at the routes, controllers and models. This helps me get a general overview of interactions and see how they match up with what I'm seeing in the browser.

And as always, I grep the fuck out of it.


- Najaf Ali

Find this article useful? Sign up to our mailing list to get updates like this in your inbox every week. No spam, and you can unsubscribe at any time.
Give me the goodies