Through this blog post, I would like to share few tips and tricks for getting involved into the existing Rails application. It's hard to lay the architecture of the project and start it from scratch, but it's equally difficult to get involved into existing project. Things may go bad if the project is not well documented and ample amount of tests are not present. But even getting into an existing project with good documentation and well-written test are difficult. Well documented project will have lots of documentation that you have to go through to understand the project which can be frustrating at times.
I would like to share few steps that I follow to understand the existing project.
Reading the documentation if it exists
Here comes the boring thing that we developers have to do. If you like reading documentation believe me you are not a developer and If you can't read a documentation then you can't be a developer. Jokes aside, we all know how important it is to go through project documentation. But how much documentation you should go through before getting your eyes on some code. You should read as little documentation as possible at the beginning. Yes, you heard it right! But once you have used the application as the end user you can come back to read more documentation. If you are new to the project domain it might be difficult to understand the documentation and you have to go little deep into the documentation. The first big project that I worked on was about currency exchange (Financial domain). There was around 300 hundred page documentation with lots of terms which I wasn't aware of. Some terms were general terms while some were project specific terms. Documentation lacked the description of general financial domain terms and only have the description of project specific terms, which made it tough to understand the project. Frustrated with documentation I made a choice to skip the documentation for a while and got started with the project with the little bit of knowledge that I have gained from the documentation. After few months, I realized that it was a wise decision to skip documentation.
Caution: This is not true in every project especially API based applications where application might have good documentation.
**"Just read enough documentation to get you started with the project. Come back when you require more information"**.
Only good part of not having a documentation is that you don't
have to read it
Using the application as end user
Using the application as an end-user is a little relaxing work. You don't have to scratch your head to just try the application and time spent on this process would be the most peaceful time in developers life. Sometimes though this step may be frustrating too. If the workflow of a project is not simple and you have to follow multiple steps to do something right, it can be frustrating and this frustration is inversely proportional to the amount of documentation.
I like to try some simple application features and then slowly moving towards big features. Using the application as end-user will give you the bigger picture of the project that you won't get by looking at the code. Even if you are good at understanding code, directly diving into code won't help you much. If you have not worked in a particular domain to which the project belongs, it might be even confusing to understand the workflow of the project. The knowledge you have gained from the documentation can be tried out in this step. Sometimes you may get stuck in some workflow, you can leave them if it's taking too much time. If you are not the first one in your organization to start with the project, you can ask other teammates who have started early for the help in using application. You can also check tests which, may give you some idea of how does the application works. Once you have tried few things in the application, you may have several doubts and you can again take a look at the documentation and this time you can dig little deeper.
"Start by using smaller feature and move towards bigger one"
Few not so necessary steps
Once I have little understanding of the application, I like to open Gemfile to just take a glance of all the gems used in the application. Looking Gemfile might not help you much, but I like to take a peek into Gemfile.
Checking how the project is organized (directory structure). Most of the Rails project will have the same directory structure. The project may have some extra directories (for eg: services and presenters) which you can look into and get an idea of what code goes where (project specific conventions). Working on Rails comes with advantage as it follows "Convention over configuration", which will help you in quickly understanding the project. Above steps can be done at the later stage of your involvement in the project.
"Knowing about project-specific conventions will help in quickly browsing through the code"
Looking into Primary Domain specific model
Almost in every project we have "User" as a primary model and system are built around this model. Each project also has another primary model which is specific to the domain and its good to look into this model to start with. You can easily figure out domain specific primary model. Some example of a domain and its primary model are.
|Learning management system:||Course|
In the recent project (Rayku) that we did, which is a learning management system we have a model "Course" which was a the primary model and entire system was build around it. Looking into the primary model may help you understand the objective of the application. I just like to spend time looking at associations that the primary model have with another model. This helps in better understanding of the project. Before exploring the primary model, you should check all the attributes (columns) of a model. You can start with looking at associations and checking attributes of associated models. Don't get excited and try to find an association in associated model and enter the infinite loop of association. Initially, it's good to only check attributes of models directly associated with the primary model one by one. I like to leave has\_many through association as it involves two levels of association. The primary model would have lots of association defined and you can leave few associations which you think might not be that important. If the project is not too complex and have less then 30 model you can generate an ER diagram using gems like Rails erd ([https://github.com/voormedia/rails-erd]) . ER diagram can give information of the application database structure and we don't have to manually check associations on the primary model. Generating ER diagram for the large project might not be very helpful. Once you know a little bit about the database structure and model association, you can start checking methods in the primary model. You should not go deep into understanding each method. You should just check what all stuff are already written and should try to imagine the working of the application in terms of code. Once you have finished checking primary model code, you would have little better understanding of the project. If looking into the primary model is generating lots of doubts, it means that you are digging too deep into code. Believe me it's not the right time in digging too deep. Best time to understand the project in details is while working on the feature. If you try to go into details too soon, you would be just be hurting your brain and that too without much outcome.
"Avoid going too deep into understanding each model method. Best time to understand the project in detail is while working on the features or enhancements"
Checking Authentication and authorization system of project
It's good to know about authentication and authorization before starting to work on any feature as authentication and authorization are not built for just one feature, but are utilized throughout the system. So whichever feature you are going to implement would most probably include authentication and authorization. You can check for different gems used in the project for authentication and authorization and read gem documentation. Yes, the documentation. The boring part of developer life returns ;). But this time its little fun in reading the documentation because it's related to some practical implementation and not just a theory behind the project.
"You are definitely going to use authentication and authorization in some point of time. It is better to have idea of how things work before using it"
Checking code related to the feature which you would be developing after understanding the project
Once you get the bigger picture of the project, you can focus on the smaller parts. You can focus on the feature that you will be building. Till now you might have a good idea of what things will be required for building the new feature and which part might get affected. Now it's time to get into details of the project. You can check all the features on which your feature depends on and try to understand the workflow. At this stage, you have to go back to documentation and read things which would be important for your feature. You can see specs for knowing how a particular feature is intended to works. And after so much of trouble you can get back to the real work.
Don’t be afraid of large existing applications. It's fun to work on complex existing projects. You will get lot of things to learn, which is impossible to learn while building the project from scratch. When you build the project from scratch, you will follow the same pattern of coding that you are fond of and would never try to go out of your comfort zone to try something new. You don't get this comfort while working on the existing project. You will find things that you have never heard about. You will get to see the code written in a way which you have never imagined of. You will find different project specific convention. And all this experience will add some shiny stars to your portfolio. So get involved and start coding :).
Hope this post help you to get involved in existing Rails application.