As an employee, freelancer, or consultant, you inevitably end up with a foreign codebase on your plate at some point in your career. In a way, inheriting a software project is much like receiving the keys to a house or car you don't know anything about. You hold your breath, afraid for what is about to come. But you are also a little excited, curious to find out what you will be working on for the next weeks, months, or longer.

A new project can be overwhelming. Depending on its size and state, opening a project for the first time can be downright shocking. Don't let this intimidate you, though. Some things are hard, but that doesn't mean they are impossible.

Take your time to explore the codebase and learn more about the project as you go. The first few days can be disorienting and it may feel as if you are not making any progress. And that is fine.

First Things First

Talk to the Previous Owner

If the previous owner of the project is still around and able to do a formal handover, then you are in luck. This is a major advantage. Prepare a list of questions and fire away during the handover. Don't be shy. You are new to the project. There are no silly or dumb questions.

Is the previous owner not around, then try to get a hold of someone who worked on or is familiar with the project. That is the next best thing.

Source Control

Whenever a project is thrown into my lap, the first thing I do is clone the repository. Is the project not under source control or, even worse, someone tampered with the repository's history, then that is the first red flag. In that case, your first task is to create a repository for the project. If things go haywire, it is easy to retrace your steps.

If the project is under source control, then take a close look at the commit history. For now, the most important questions are:

  • Who made the first commit and when was it made?
  • Who made the last commit and when was it made?

The time of the first and last commit tell you a lot about the state of the project. You may even be able to contact some of the people that worked on the project. Source control is invaluable for any software project.

Compatibility

Depending on the software project, you need to make sure your development environment is compatible with the project's technology stack. A Cocoa application, for example, requires a machine running macOS with a copy of Xcode installed.

It may even be possible that you need a specific version of macOS or Xcode to bring the project to life. Again, if you can talk to someone that used to work on the project, you are saving yourself a lot of time and frustration.

Build & Run

The moment of truth arrives when you compile the project for the very first time. Give it a try. Build and run the application on a device or in the simulator. This step is critical because it reveals some of the project's dependencies, such as third party frameworks and libraries, and it can also expose some early problems.

If the project uses a dependency manager, such as CocoaPods, then you may need to install the dependencies first before you are able to compile the project.

Once you have successfully built and run the project, you have reached a first important milestone. You can now start to explore the project and collect information.

Collect Data

With the project up and running on your development machine, it is time to get to know your new best friend. It is important to understand how the project works and, more importantly at this stage, find out what its requirements are.

For a Cocoa application, for example, the deployment target is an important piece of information. It tells you what APIs you can use and which devices the application is compatible with. Are you dealing with a universal application or does it only support iPhone and iPod Touch? Has the project been updated for retina displays? Do you think that is a silly question? Think again.

Some projects have been collecting dust for years. This can sometimes mean that you need to make significant changes before you can submit a build to Apple's App Store. Since June 2015, for example, Apple requires new applications and updates to existing applications to include 64-bit support. If the project depends on a third party framework or library that hasn't been updated in years, this may be a problem.

Dependencies

Speaking of dependencies, you are probably starting to get a pretty good picture of the project's dependencies. It is time to take a closer look. Are the dependencies managed by a dependency manager or are they included in the main project?

With a bit of luck, the previous owner used a dependency manager to separate the dependencies from the main project. In that case, it is straightforward to verify the current version of each dependency and, at a later stage, update them.

In some cases, dependencies are included in submodules or, if you are less lucky, they are mixed in with the project. The latter makes updating dependencies a pain. Migrating third party dependencies outside the main project with the help of a dependency manager is a worthwhile investment. It will save you many hours and headaches.

Working on the Project

How you approach a project largely depends on the time you are allowed to spend working on it. If you only need to step in to fix a handful of bugs, then it isn't worth spending days or weeks familiarizing yourself with the codebase.

Are you tasked to implement a major feature, then it is key that you know how the application is architected and how it operates. If you are the new owner of the project and in charge of maintaining the project for the foreseeable future, then you have the luxury of investing time and energy to clean up the codebase, refactoring neglected parts, and making the project yours.

Document Everything

No matter what project you work on, it is important to document as much as possible. The README of the project is a good starting point. For larger, more complex projects, it can also be useful to document features or include an overview of the application's core architecture. It helps other developers become familiar with the project and it also benefits you, the maintainer, in the long run. By commenting your code, writing sensible commit messages, and maintaining a list of bug reports, you have most of the tools you need to stay on top of your project.

What's Next?

What's next? That is a good question. In this article, we only scratched the surface. Starting work on a foreign or legacy software project can be messy. It may push you out of your comfort zone, but that is a good thing. Leaving your comfort zone from time to time keeps you sharp, forces you to be creative, and prevents you from becoming complacent.