Vladimir Sarić wrote this on January 14, 2013

Bringing life to your old Rails application, part 1

In this two-part article I will present the steps we take when taking over an existing application, be it to add new features or do a complete redesign.

Communication is key

One thing that many development teams seem to neglect is how crucial good communication is. Even when aware of it’s importance they seem to forget to include the stakeholders in the flow.

A mistake which we see regularly repeated is the extensive use of emails as the main form of communication. Emails are perfect when first negotiating with the stakeholders or when you just need to get in touch, but are far from perfect when it comes to staying in the loop, discussing features or getting an overview of the app when development work begins. Instead, we suggest using a good project management tool for this.

It’s also important to keep track of upgrade progress, new features and issues. For this we suggest using a good task management tool and we encourage everyone on the project to use it, including the designers and stakeholders. For example, a stakeholder can notice a bug while testing a feature on the staging server and can easily assign a task to a developer to fix it.

Another thing we encourage is code review. When a developer implements a feature he then requests from a fellow developer to review it. This can lead to significantly better code for a minor time investment. When working on an existing application and having past developers on the project in some capacity, code review is a perfect way to get some feedback from them.

Get to know the application

Many development teams when taking an existing application under their wing make the mistake of diving right into code without actually being familiar with it.

The first step in the familiarization process should be to put yourself in the seat of a general user and actually use the application.

After getting “the feel” for the application, it’s very important to talk to the stakeholders. Their view of the service they are building and the goal they wish to reach is crucial, and because of that, the development team has to be in the same mindset as them.

It’s also very important to talk to past developers. They can give really valuable insight into the application, e.g. what is it’s current state, which technologies did they use and why, what obstacles did they have to overcome.

Another good idea is to read the documentation. Documentation’s state can be a good indicator of the general state of the application. Documentation doesn’t have to be extensive - it should mostly serve to get new developers faster on track. Quality code and properly written automated tests, which every modern application should have, can serve as documentation. Meaning, it’s better to use valuable development hours on good code than wasting them on writing extensive documentation.

Good local development environment

Before actually starting to work on the application, it’s important to set up a good development environment. This, of course, is true not just for an existing application, but for a new one as well.

A constant in our development environment is the use of virtual machines. Each of our projects has it’s dedicated virtual machine. Since applications can have complex environment requirements, in the form of 3rd party libraries, creating a snapshot of virtual machine’s current state, before each major installation or configuration change, allows us to restore the virtual machine to a previous state if something goes amiss. Also, being able to share virtual machines between team members, dramatically cuts down required setup time. It’s enough for just one member to set up the application on a virtual machine and afterward just share it with the rest of the team.

To avoid any surprises when deploying to production, it’s important to remember to match the development environment as close as possible to the production environment. Ideally, it should be a perfect clone. Using the same setup script for the development, staging and production environments can help you achieve this.

When working on an existing application, it can be a good idea to import the production database to the local development machine. Working with real data is always better than working with test data, since you get a better picture. But, you really have to be careful: for example, emailing real users with your under development emails is never a good idea.

Implement automated tests

Every application needs some form of testing performed. While manual testing can be slow and error prone, automated test are precise and very fast. Most importantly automated tests save time, and with that money.

Those benefits are mostly the result of developers having confidence to introduce changes to the application without having to worry that they broke something unrelated. To confirm that, all they have to do is run the automated tests. This process is even more enhanced when coupled with continuous integration and for this purpose we recommend our very own hosted continuous integration service Semaphore.

These days having automated tests has become a standard, especially when the application is developed practicing Behavior-driven development, but if the application is a year or two old, it’s not uncommon for it to not have them.

If the application doesn’t have automated tests, before introducing changes, be it with updating existing features or adding new ones, it’s a good idea, or more of a necessity, to add them. This process doesn’t take long and it’s benefits, as mentioned earlier, are huge. In this case you cannot aim for very high test coverage. Instead, we work with stakeholders to identify the most important parts and use cases of the application and cover them with tests first. From that point, a good rule of thumb is to write tests for every new part of the system that you touch while working on fixes or improvements.

Here’s an example of an automated acceptance test which can be both written and understood by both the developer and the stakeholder:

Feature: Invite friends and earn $$$

  In order to earn money
  As a user
  I should be able to invite my friends to join

Scenario: Inviting a friend through email
  Given I am logged in
  And I am on the invite friends page
  When I invite my friend "john@gmail.com" by email
  And he signs up through the link in the email
  Then I should see "john@gmail.com" as my referral on the invite page