How to grok a Rails application for the first time
Diving into an existing Rails application for the first time can feel a bit overwhelming, especially when you’re trying to piece together how everything works. In this article, we’ll walk you through the process of truly understanding (or grokking) an existing Rails app for the first time.
At FastRuby.io, we often dive into Rails applications that have been developed by multiple people over the years. Through this experience, we’ve refined a process that combines both automated static analysis tools and manual code review. In this article, we’ll focus on how we manually grok a Rails application when approaching it for the first time.
Our process is flexible and can be adapted to meet the specific needs of each project. The main goal is to uncover insights into how previous developers approached and structured the application.
Modes of Operation
When we examine an application for the first time, we use two modes of operation: quantitative and qualitative. The quantitative mode involves a high-level overview, helping us get a big-picture perspective on the codebase. In contrast, the qualitative mode is when we dive deeper into the code, examining specific patterns and decisions to better understand the application’s inner workings.
1. View Rails stats
The first quantitive check we do is run the bin/rails stats command. This provides an overview of the application’s
models, controllers, and views. It also gives us insight into the lines of code, the code-to-test
ratio, and the code-to-comment ratio. The goal here is to gather useful data about the application
while also gaining a better understanding of the team behind it. Here is an example of what you might see:
bin/rails stats
+----------------------+--------+--------+---------+---------+-----+-------+
| Name | Lines | LOC | Classes | Methods | M/C | LOC/M |
+----------------------+--------+--------+---------+---------+-----+-------+
| Controllers | 591 | 502 | 15 | 69 | 4 | 5 |
| Helpers | 126 | 103 | 0 | 17 | 0 | 4 |
| Jobs | 2 | 2 | 1 | 0 | 0 | 0 |
| Models | 242 | 185 | 8 | 30 | 3 | 4 |
| Mailers | 4 | 4 | 1 | 0 | 0 | 0 |
| Channels | 8 | 8 | 2 | 0 | 0 | 0 |
| Views | 1282 | 1133 | 0 | 0 | 0 | 0 |
| JavaScripts | 294 | 225 | 0 | 18 | 0 | 10 |
| Stylesheets | 1369 | 1218 | 0 | 0 | 0 | 0 |
| Libraries | 18 | 13 | 0 | 0 | 0 | 0 |
| Controller specs | 879 | 702 | 0 | 0 | 0 | 0 |
| Feature specs | 1392 | 1063 | 0 | 1 | 0 | 1061 |
| Helper specs | 10 | 9 | 0 | 0 | 0 | 0 |
| Model specs | 347 | 281 | 0 | 1 | 0 | 279 |
| Policy specs | 37 | 29 | 0 | 0 | 0 | 0 |
+----------------------+--------+--------+---------+---------+-----+-------+
| Total | 6601 | 5477 | 27 | 136 | 5 | 38 |
+----------------------+--------+--------+---------+---------+-----+-------+
Code LOC: 3393 Test LOC: 2084 Code to Test Ratio: 1:0.6
2. Read the README
The README should outline the application’s purpose, setup instructions, and test suite details. It might also include information about the architecture and deployment process. A quick scan of the README at this stage provides valuable insight into how well the team documents and maintains the project.
3. Look at the Gemfile
Still with our quantitive hat on we review the Gemfile. The Gemfile gives us an idea of what libraries the application is using. It will also give you an idea of the Rails version the application is using. Some Gemfiles contain valuable comments that can give you hints about the application’s architecture. We keep an eye out for any gems that we are not familiar with, as they might be important to the application. Review interesting or unknown gems, to see how a gem could potentially add to the complexity of the application
4. Look at bin/setup and bin/update
To deepen our understanding of the codebase, we review the bin/setup and bin/update scripts.
A quick look at these files helps us gauge how easy it is to set up the application. These
scripts can also reveal how effectively the team behind the application automates repetitive
tasks.
5. Get an overview of the tests
Next, we take a look at the test or spec directory to get an overview of the tests. This will help us assess the application’s test coverage and see how the tests are structured.
ls -l spec
# or
ls -l test
To go a bit deeper we may review a few tests to get a sense of how they’re written and to form a general impression of their quality. It also gives us insight into the testing strategy and how the tests are executed.
6. Look at the routes
Next, we check the routes file. This gives us a clear picture of the application’s routes and how they map to controllers and actions. It also offers insight into the application’s resources and how they are nested.
7. Get an overview of the models
Check the app/models directory to gain an overview of the models. This will help us understand
the application’s domain model and how the models are structured.
8. Get an overview of the controllers
Take a look at the app/controllers directory to gain an overview of the controllers. This will
provide insight into the application’s controllers and their structure.
9 Going deeper
At this point, we may decide to put on our qualitative hat for the first time, diving deeper
into the application to fully understand how it works. We might encounter an unfamiliar
pattern or a piece of code that’s difficult to interpret. When we come across a method that we
don’t understand, we use source_location to locate its definition—especially if finding
it with grep is challenging.
method(:some_method).source_location
Conclusion
With experience, you’ll find that a codebase reflects the team that built it, especially in how they communicate and collaborate. Small details—such as specific RuboCop rules—can provide insights into the team’s dynamics and coding standards. When we review a codebase for the first time, we start with a quantitative approach, building a high-level understanding of the application. Once we have this foundation, we shift to a qualitative approach for deeper insights. The observations we gather can also guide our communication with the client, helping to build trust and strengthen our working relationship.
I hope you found this post helpful in navigating and understanding Rails applications. Whether you’re diving into a new codebase or looking to improve your existing project, these insights can guide you in fostering better communication and collaboration within your team. If you have any questions or thoughts, feel free to reach out to us!
Need help with your Rails application? Talk to us today!