Greenfield vs Brownfield

There’s nothing better than cracking open your laptop, selecting “New -> Project”, and starting to build an app. At this point your codebase is flawless, your app builds and runs in seconds, and there’s no tech debt. Every thing is in the right place, and you feel like you can conquer the world.

But there will come a time when you have to work with other people’s code. You inherit an existing codebase when starting a new job. Or you get a new client who has a working app that needs features added or production bugs squashed. Or you get the opportunity to rescue a project that’s over budget and timeline and needs to be shipped ASAP. Whatever the case might be, there’s an existing codebase that has perceived value and its up to you to add to it. So where do you even start?


At LunarLincoln, we like to start by carving out some time to review the project. If there’s existing documentation, start there. Now that you’re working on the project, documentation is your responsibility. Make sure to update existing documentation if you find errors. If there’s no documentation, document things as you go. Then use the app like a real user would. Start making a list of questions as you go and work with stakeholders or previous developers to get answers to those questions. Having a good spec is the first step in contributing to an existing codebase.

Code Review + Red Flags

After you know what the app’s supposed to accomplish, dive into the code. Start by building the app from the latest commit that was deployed. Be on the lookout for red flags (and yes, document these as you go).

Red flags come in many forms, and you’ll get better at spotting them the longer you work with apps. Here are a few we typically look for when onboarding a codebase: 

  • An egregious number of build warnings
  • A disorganized project structure
  • A few classes with a lot of code in them or a lot of classes with almost no code in them
  • Poor or inconsistent naming
  • Breaking the defined architecture of the app (i.e. if MVC seems to be the convention, having the view accessing the model layer directly)
  • Code that solves widely solved problems
  • Dependencies that have little to no community around them

Fix Something Small

From there, take a quick, deeper dive into the project to get a feel for working in it. A great place to start is trying to fix an existing bug. This’ll give you an idea of what working in the codebase is actually like. It’s impossible to fully understand a codebase that took months to build in a review lasting hours, but at least you’ll have an idea of how to set expectations moving forward.

Document + Present Your Findings

Once you’ve had a chance to review the project, make a list of things that need to happen to move the needle on the project (you were doing this as you went…right?). Then categorize that list by urgency. You’ll probably want to fix everything before getting started with new features or bug fixes, but some things will absolutely be more urgent that others. The important part is that you communicate what you find to your stakeholders, agree on a plan to fix things, and start producing value. For existing apps, try to remember that the app people are using in the wild was made from the code you already have.

Become the New Code Master

Switching developers on a project is an expensive undertaking. Save yourself a headache later by reviewing the documentation, app, and code up front. Then leverage the findings in your review to lay out expectations and a roadmap for continuing development on the app.