Paying off technical debt vs not

I have been working on a Rails application as a freelance contractor for about a month now.

The gist of the project is this. Take an existing Rails application that’s live in production, and morph it into another product using the existing codebase. So, this isn’t really a brand new project per se, but more of morphing of an existing product into a new product.

Just to give context into the project, the current product that’s live in production is called Laflife What the current product does is that it cleverly figures out the user’s sense of humor through various “tests” that gauge your reaction to humorous comics. My client, who is the owner of the product, wants to turn this existing product into a dating app where it matches people based on their compatibility using the users’ sense of humor.

I jumped into the project thinking that this will be a simple project where we remove some existing features, add a few new features, and make some copy changes throughout the app. However, as soon as I jumped into the project, I’ve noticed that this was one of those codebases that have been touched by many freelancers over the few years with very little thought put into project maintenance.

The first thing that I’ve immediately noticed was that there wasn’t much of a test suite. In fact, both RSpec and the default Rails test suite were installed with a few tests written in both testing frameworks. I decided to remove RSpec tests entirely (there were like three tests in total) and replace it entirely with the default Rails testing tool as it’s my personal preference.

The second thing I’ve noticed was that there wasn’t a README explaining how to setup the project. Also, there were errors that I encountered in the pre-existing scripts to help with the setup process. Thus, I went through the setup process, fixed the existing scripts, outdated and conflicting Gemfile and individual gem versions, and wrote an extensive README detailing how to set up the project for development. I thought this was something important to do for any future developers who would be working on the project.

Not all was bad however. I was impressed that the project was running on Rails 4, despite the project having started a long time ago prior to Rails 4.

Once those two tasks were completed, I began working on a few tasks. The first problem that I immediately ran into was that I couldn’t find any documentation for Foundation 4, which was the version of Zurb Foundation the app was running on. At the time of this writing, the latest version of Foundation is 6. I went digging through the internets trying to find the documentation for Foundation 4, and unfortunately, the links for the documentation site for Foundation 4 were broken. This meant that I had to “guess” on the class names, JavaScript method names, and etc when I was trying to use the library.

I also noticed that a lot of the gems being used were no longer being maintained, which meant that if we upgrade Ruby or Rails version in the future, there’s a possibility that those gems may stop working altogether. Not only that, I’ve noticed some gems added were simply not being used. This lead to me looking through the codebase to see if there were any dead code, out of date stylesheets, JavaScript files, and etc. I’ve found that the CSS and JavaScript files weren’t in the best condition, and that there were some dead code lying around in the codebase. I’ve also saw that pretty much all of the routes defined in the routes.rb file were difficult to wade through due to not following the resources convention, but rather manually defining every route via get 'blah' => 'some_controller#method_name'.

As the solo developer for the project, I thought that I had two options. One is to continue working on the codebase in the current condition and just knock out everything that the client had asked for. Granted, I would be able to make faster progress in the short term, but it would feel like putting more bandages on top of an open wound, which will never heal. Second option was to tackle the technical debt I saw first, and then continue on the project. This option would take longer, cost the client more money in the short term, but ultimately save the client money in the long run if the application ever became successful. Also, if the application ever became successful, I would probably end up working on the project on a longer term basis, and I definitely prefer working on a healthy up-to-date codebase.

I communicated to the client with my “consultant hat” put on that I recommend we do a few things. First thing we need to do is upgrade Foundation from version 4 to 6. This will be painful because it would break a lot of existing UI, and I would have to manually fix them, but considering that we’re two versions behind and documentation for version 4 cannot be found on the internet, this is worth the investment if we look at it from a longer term perspective. During this process, I will be cleaning up the stylesheets and making it more modular.

Second thing we need to do is to upgrade Ruby to the latest version which is 2.4.2 at the time of this writing and upgrade Rails to the latest version as well which is 5.1.4 at the time of this writing. I figured that this is worth doing since we’re in the upgrade process either way and we don’t have to worry about upgrading it down in the future after the app has been released.

I began working on the upgrade process and realized that the upgrade process itself is a pretty large task, worthy of being a project of its own. During the beginning part of the process, I questioned myself whether A) this was the right decision and B) if the client would be happy with me actually taking this much time working on a project that’s difficult to see visibly.

As a software developer working directly with the stakeholders, I still find this balance difficult to strike. In the case of this project, I strongly believe that tackling the existing technical debt that exists is the utmost priority. In fact, I’ve seen that this project has gone through multiple developers. I wouldn’t be surprised if a few of them dropped off the project because they didn’t enjoy working on a project with technical debt. I believe that tackling this technical debt now can have the potential to attract and retain talented developers. Also, I believe that taking the time to pay off this technical debt now will significantly speed up development, ultimately saving time and money for the client.

However, the part of this that bothers me is that the client won’t be able to see any visible progress on the project. While the client is very smart and capable, he isn’t a developer, thus he may not fully understand that significant work is being done on his project even though he’s not seeing any visible progress. While I have communicated with him that paying off this debt is important, I’m still concerned due to not making “visible” progress at least for a month or two.

For now, I’m going to follow my gut and go through the Foundation/Ruby/Rails upgrade process.