So you’ve just received a new Rails project. What comes next? Or what should come as next? First of all, grab pen and paper. I’m not kidding. At the end of the day you will toss these writings in the trash, but for now your notebook is your most valuable tool. Ready? Go through all the points below. If you encounter something odd or different from the normal Rails way, then write it down.
Step 1: Read the README
It sounds obvious but bear with me. More obviousness coming your way in a second.
Every software project should have a well documented README file, with a detailed description of the codebase and the application's business model. If your new project lacks one then, guess what, write it down. TODO: create a good README from these notes.
If your README is good, then don’t get caught in the trap of reading it all right now. Read the introduction. Maybe skim through the general sections about architecture, patterns and third-party services. Skip detailed and long paragraphs. You will return here later.
Step 2: Browse the directory structure
This is again obvious; told you. There is no need to open your editor yet. Just go to your project directory and execute:
This should give you a long list of all the folders, subfolders and files in the project. Here are some questions you can ask yourself:
Do you recognise all names?
Maybe there is a folder called app/policies that you don't recognise? Something that is done in a non-standard Rails way? Are there more directories in the root of the project itself? Maybe a folder with assets actually keeps a dozen front-end applications?
Remember to note anything suspicious, weird, non-standard, longer or shorter than usual, and so on. Write it all down.
Is any folder particularly full of files?
If your assets/images directory has a lot of cat pictures, it's a good indicator of possible issues. The same goes for many other directories. Even a shallow in depth /lib directory with a large number of files may indicate possible problems for you if you ever need to modify those files. It would be a great place to mark for future refactoring.
Step 3: Browse the Gemfile
This is what I like the most. Dive right into your Gemfile and see what gems and technologies your new application is using. Even if the README from the first step is lacking, you should find a lot of answers here.
Visit the homepage or browse the source of every gem
Go through them one by one. Presumably each gem will have its own repository which you can visit. Skim each README you find. You don't have to learn everything now but it's important you know about the possibilities.
Keep note of locked versions
If your Devise version is locked at 4.0.1 you should check why. Browse the git history and read the commits' messages. If you are lucky, maybe previous developers have left a clue there. Otherwise, search through the issue tracker and the gem's repository to find out why the specific version is so important.
A note about patch versions: according to semantic versioning, patch versions can be updated without the need to worry about backward-compatibility. So if you find your gem in version 1.0.1 and newest version is 1.0.3 it's fair to assume you can update it right away.
Grouping gems into groups such as production, development, test, and doc is a standard Rails practice. Any other group is a worthy anomaly to notice though. No developer would create one if there was no purpose for its existence. If you find an extra group, grep your source files for occurrences and see what's the deal.
Before we jump into reading models’ source code, it's a good idea to browse the contents of db/schema.rb. Familiarize yourself with the existing table names and attributes. Other important things to look for, depending on your database engine, may include:
missing indexes for relations
existence of uniqueness indexes
attributes of a hstore type
date vs datetime attributes
Ah, the models. Often fat and responsible for everything, at least when you are just starting a refactor job. A place to look for a lot of answers. For example:
You can of course see that in db/schema.rb, but looking at all those belongs_to and has_many keywords seems faster, at least to me. But there is an even better way to learn all the relations. Just use gems such as Rails ERD which can graph all your relations and present them in a single PDF file.
What are your first steps when receiving a new rails project? Share your thoughts in the comments below!