Ruby on Rails is a mature technology, and probably that’s why many people say that it’s a dead technology. But it’s not. Fewer developers start new projects with Rails, but hundreds of thousands of applications are in the maintenance mode. This is the reason why the skill of quickly adapting to the legacy code is so essential for you as a Rails developer.

Joining the legacy project is not easy, and the reality might overwhelm you if the documentation is not well-maintained (which is the case in many projects). That’s why I decided to create a list that would help you familiarize the business logic of the legacy application made with Rails.

Thanks to this list, I successfully joined several dozen legacy projects and started effective development from day one. Here is the list.

Look for any documentation

This might be obvious for you, but I worked with too many developers not to know that sometimes we miss something that should be standard.

After you join the project and get access to the source code, it’s good to do the following:

• Look for the README.md file and other files in the markdown format that developers can place in the application’s source code. Files with that format often contain helpful information about the application behavior or the setup instructions.
• Check the wiki pages that are published on the platform where the source code is hosted.
• Ask your team members if they have some “private” documentation or notes about the application that they can share with you.
• Search through the company’s google docs, dropbox paper, or any other place where documents can be stored

In the perfect world, you should receive all the valuable documents during the project’s onboarding process. Still, the reality often is different, so it is good to know what we can do ourselves to collect more information about the application.

Check the Rails version

With every new release of the Ruby on Rails framework, new features are added that were not available in the previous versions. Knowing the version of Rails used in the application, you can tell what features won’t be used and which can be used.

If you are aware that the navigation through the project’s files seems to be more effective, you will spot the configuration files, such as webpack or ActionCable.

Gemfile inspection

The Gemfile contains all gems used in the application, so a quick review will give you a clue about the business logic inside the app and the tools that are in use.

Pay attention to those details:

• The test group will contain gems used only in the test environment so you can quickly get an overview of the test suite used in the app and the framework that is used for testing
• The development group will contain gems used for the development by the developers from the team, so you will get a quick tip on how to improve your efficiency when working on the app’ development
• Look for gems where the git repository is specified, as those gems can be internal company gems or forked versions

The number of used gems is not always a good criterion to tell if the app is extensive, as some smaller apps can also contain many gems (which is probably not a good sign).

Environment configuration

By looking at the config/environments/ directory contents, you can quickly get information about the environments used in the application. Each file is responsible for one environment, so most likely, you would see the following environments:

• production
• development
• test

In many cases, there would also be the staging environment and some other environments used for performance tests, for example. Go ahead and inspect every file to collect helpful information about:

• the way that e-mails are handled - in the production you would discover which provider is used and in development and stating it would be probably letter opener or similar solution
• caching policy
• logging policy

All of this information will help you better understand the setup of the application and which tools you should familiarize yourself with to make the development process efficient.

Search for .env files

Environment files are an essential part of the application, so you should familiarize yourself with them if such files exist in the source code. In addition, you would probably need to create the local version of such a file to run the application in the local environment successfully.

Also, the knowledge about the contents of the environments files is beneficial for you as a developer because:

• you would know what services are used in the application
• how to configure the application locally to be able to test all features successfully
• what are the naming conventions for the environment variables

When starting work on the project, search for the .env.example file that is a template that you should copy to the development environment configuration file.

Look for design patterns in the app directory

If you are not yet familiarized with the term design patterns, make sure you saw the introduction article about design patterns in the Ruby on Rails application

Design patterns are just a way to structurize the code, and in most cases, developers would place files for different design patterns inside the app directory. For example:

• app/decorators
• app/serializers
• app/value_objects

By looking at the directory structure in the app directory, you can quickly check what kind of patterns are used in the application. Of course, it is not the case in all applications as the structure can be different, but in many projects, you can see a few of those directories, and such knowledge is a nice starting point for the development.

Check the database schema

A database schema is a perfect place for collecting information about the application’s data structure. It won’t help you spot the relations easily but will give you a clue of the different formats, resources, and database constraints.

If the database constraints are present, you can expect the data in the database to be in a good format. However, some developers’ mistakes are to depend only on the Rails validations to verify if the data is valid. In some cases, such an approach can produce inconsistency in the data format between expectations and reality.

Check the routes

The config/routes.rb file is a source of truth for the endpoints exposed in the application. Sometimes it happens that routes are split into multiple files but still the routes.rb file will be the entry configuration point.

By inspecting the routes configuration, you can get information about the following aspects:

• The endpoints that are available in the application
• The relations between given resources when they are nested
• 3rd-party addons that are mounted inside the application - for example, the Sidekiq dashboard or letter opener dashboard
• Mounted API engines that not necessarily are created with Rails

Inspect the tests

Well-written tests are a perfect type of documentation. So each time you start work on a project, look for a test or spec directory where the developers usually place the tests.

• Run all tests to ensure that you configured everything locally and all libraries are installed. If some specs are failing, ask the team members to confirm that the test suite should be green. Sometimes some tests are failing, and team members are aware of that.
• If using rspec, try running tests with the --format documentation to get a nice output from the tests’ contexts.
• Look for controllers or request tests to see what params are passed for each request and what filters are used to authorize and authenticate the user.

Click through the application

It is good to spend some time just playing with the application, interacting with different system elements, and trying other user’s paths. By doing that, you will discover how the application works and spot any aspects that are not working as expected because of some misconfiguration or missing environment variables.

Check also the db/seeds.rb file as it may contain some valuable test data that you can load to start playing with the application immediately.

It’s time to dive into the development

Now, with the proper preparation, you can start work on your first task. Of course, some developers prefer to do a deep dive into the code and start the development right away. Still, I like to spend some time investigating the application as it’s always good to have a better context of the business logic, used patterns, and application’s general rules; it can save us some time.