Here’s How to Tackle a Brownfield Project as a New Software Developer

When you start off either teaching yourself to code or go to school for it, you almost always start off by building your own basic applications from scratch.

For some jargon-y knowledge for you, these applications are usually known as “greenfield” projects.

Software web development is built upon knowing the fundamentals of how a specific language works and then eventually how a larger application interacts on the web (and potentially with other applications).

From there, most people go off and ideally become gainfully employed at either a product company, a consultancy or possibly self-employed as a freelance software developer.

As I finish up my last week at the Turing School of Software & Design as a backend developer, I can easily say that one of the best things I learned was how to take on a project that already exists — especially one that is a production level app — and implement a new feature with it.

These kinds of apps are what are commonly referred to in the industry as “brownfield,” and they will easily cause you the most grief as a budding developer.

So, why is brownfield so scary?

For my personal project during Module 3, I took on the task of cloning down Brimir, an email help desk app built using Ruby on Rails and Zurb Foundation by Ivaldi, and try my hand at ripping out their current Google OAuth and email integration with Slack’s OAuth 2.0 and a Slackbot to serve as an integration for Turing’s Slack team.

Knowing where to start as a brand new software developer with something like this is not always intuitive.

I took more time trying to figure out how everything worked together and what RubyGems I didn’t recognize did what than I was comfortable with. The momentum you usually have when building your own application, with your own test suite (RSpec is life) and gems of choice, is much different than the idleness of working on unfamiliar legacy code. It often feels intimidating to remove any line of code for fear of breaking all 150 tests another developer has painstakingly written prior to you, too.

That’s why I’m here to try and tell you how I learned to approach a brownfield project and get over that paralyzing fear of not knowing how to start.

Step 1a: Read any installation documentation for the repository you’re working on.

Seriously, do yourself a favor and read the entire README.md (if there is a decent one) and/or any “getting started” documentation that may be linked in the README first.

Step 1: Clone the repository and get it set up on your local machine.

If you’re working with a Ruby on Rails project, get it up and running so you can start taking a look at it:

cd project name
bundle install
bundle exec rake db:{create,migrate}
rspec # or rake to run your test suite

Keep in mind, there is a good chance that you might be missing some dependencies on your machine and either bundling or running your tests will throw you errors. Please refer to Step 1a.

Step 2: Isolate where your change will probably go and what methods it might effect.

Try and locate where your change will be added in the project and do some investigating. You can do this by commenting out some methods or lines of code that will most likely be replaced with your code and see what it touches by running your test suite again.

Step 3: If the project doesn’t have something tracking test coverage, add it.

I personally love the SimpleCov gem when testing my test coverage. Another popular alternative is Coveralls. Install and configure one of these options and make sure you’re aware of what’s fully tested or not (other people working on this project will thank you for it later, too).

Step 4: Write an acceptance test (or feature test) that expects the change you’ll be implementing.

Note: If the change you’re implementing is more of a database change, test on the model or service level instead.

True TDD, or Test Driven Development, is your best friend when it comes to doing something you’re not comfortable with. Write out a user story if you don’t already have one and transpose it to your test.

Once you have that checking for the desired interactions, I’d say you’re ready to start implementing your new feature!

Just remember, if something seems too unmanageable, try breaking down the problem into the smallest steps you can take. Take your time to read documentation and don’t be afraid to reach out the the original developers to try and clarify any questions you have.

You’re now a bajillion times more prepared for working at a job where you have to deal with a code base that has been around longer than you’ve been coding. You’ll thank me for it later.