This article has been translated to Russian, thanks to Leonid Suschev.
You just changed teams at work, or just started a new job. Or you found a bug in your favorite open-source app, and want to write your first pull request. But after you git clone and open app/models, you’re totally lost. Even though the Rails structure is the same as what you’re used to, it’s impossible to find your way around the code. So what’s the fastest way to learn this new, unfamiliar Rails app?
Build a project vocabulary
What is a Player, and what’s a Session? How about an Account vs a User vs a Provider?
Every app uses different terms and different metaphors. And if you don’t understand the vocabulary of an app, you’ll waste time browsing app/models every time you see a new class name. Or worse, you’ll make bad assumptions about how features work.
So, the first thing you have to do is build that vocabulary. Learn what this app is made of. And if you want to do that quickly, start by reading db/schema.rb. You’ll learn the terms the app uses, and how all its data fits together. Pay special attention to the *_id columns, so you can see how the models connect to one another.
If you’re more visual, try the rails-erd gem. It generates a diagram from your Rails models, showing all your tables and columns and how they interact. Keep a printout on your desk, and you’ll have an easier time understanding the rest of your app.
Continue with the models and plain Ruby objects
In a well-designed Rails app, not everything will be backed by a database table. To continue to build your project vocabulary, look inside app/models for extra classes and attributes that you didn’t see inside db/schema.rb.
Don’t spend too much time here yet. It’s easy to get lost in how things work. You’re just here to fill out your project vocabulary.
As you learn more about the parts your app is built from, you might wonder why certain objects exist, or why they fit together the way they do. And that’s the point of the next stage.
Try the app, and find out “why”
Once you feel comfortable with the objects the app uses, start the app up. Click around and explore. If there’s documentation, it can help guide you. Otherwise, just see those terms you just learned come to life.
As you use the app, you’ll start to see it from a higher level. You’ll notice that there are reasons why models have the associations they do. Why they’re grouped together. Why those class names were chosen. Maybe they all appear on pages together, or are built from the same form.
And when you start to understand the parts the app is built from and why they exist, you’re ready to figure out how it all works.
Figure out the “how”
By now, you know enough about the app to learn it in detail. You won’t get distracted by new terms and new interactions. You can pick one thing you want to learn, and follow it all the way through.
There are lots of ways you can go from here. These are a few of my favorites:
- Browse the UI, and think: How could this feature be built, knowing what you know about the pieces? Can you guess? Use a debugger to confirm your guess, or discover how it actually works.
- Pick a test case and follow it all the way through the app. Either read through the code, or explore it with a debugger.
- Pick a route or controller action. Can you figure out how to reach that controller action from the UI?
This is also a good time to go back through your models and plain Ruby objects. And this time, you can go into the details of how the models work.
Become curious about the app. Find gaps in your knowledge and close them with a debugger and the code.
Why not start with the tests?
I’ve always heard people say, “If you want to understand a codebase, start with the tests! Tests are executable documentation!”
But this has never worked for me. Test cases are too narrow, too detailed. If I learn from the tests, I feel like I’m missing the bigger point of the app.
In order to understand something as big as a Rails app, or even most gems, I’ve always needed an overview first. I have to know which components make up the app, and why they exist.
But absolutely, make sure the tests run. If they don’t, you’re working with a broken system. And you can’t rely on the things you discover from a broken system.
What, to why, to how
To understand a new Rails app, go through these three phases, in this order:
- What parts make up this app?
- Why do those parts exist? Why are they put together that way?
- How does each piece work?
That will give you both the broad point of view and the narrow knowledge you need in order to make that new app yours.
P.S. I’m releasing Practicing Rails next week. So if you want to get the 25% early access discount, you’ll want to order it soon!