Scary New Code

I’ve been writing software on my own for years, but one of my biggest challenges since starting at Made has been learning how to work in a team and get up to speed with huge, alien codebases in a short amount of time.

I can’t assume I know and understand everything that’s going on in an app any more, and working in a support role means I’m having to get used to lots of apps quickly. The following are some tips I’ve received and learned since I started, old tricks which have become more useful than ever and techniques I want to work on going forward.

You don’t have to know it all to work with it

I came to Made with only a few weeks knowledge of Ruby and Rails, but I’ve learned more from diving into real app code and the source code of our most used gems as I’ve had from documentation and guides. Although software can get complex and codebases can get huge, when you get down to it, code is simple. Methods take data and change it or send it somewhere else. If you know one programming language, you can suss out others without too much trouble.

The same goes for entering a codebase you’re unfamiliar with. No matter how disconcerting staring at 4000 files may be, when you find the relevant place, you’re in your comfort zone. Take the time to read through related code when working on a feature or bug fix, the extra knowledge will boost your acclimation to the project.

Use what already exists

The underlying MVC principles of Rails are expressed elegantly through its directory structure and class conventions. In general, if your frameworks and libraries are strong enough for you to use them in production, they’re going to be smart enough to have a good separation of concerns and readable structure.

The same goes for your app specific code, and this simplifies adding new code – you should follow the conventions of the framework or existing code wherever possible and examine similar functionality already in the app. When debugging, once you have found where functionality is being expressed it’s often easy enough to reason about how and why it works the way it does.

Foreign code is still just code, use what’s there and you’ll learn the overarching structure as you go.

Check the tests

When investigating a feature or module you’re not familiar with, checking a respective test can illuminate exactly what it is and what it depends on. Comparing a bug report showing an error in an existing feature to a related test can sometimes clearly show where and why a fault is occurring, and looking at factories of a unit test can show you what the requirements of a piece of code are.

As a general rule, feature tests show you how something is expected to be used, and unit tests expose how something works underneath. Hunt for some relevant tests, compare the steps to related controllers or modules and follow the trail they take through the app. What data do they receive? What is their expected function or output?

Know your dependencies

All of the code in your app is yours, and if it breaks your app it’s your responsibility. Often, errors in your app can be traced back to the way you’re using your third party libraries. Reading through documentation of a feature on Github or RubyDoc is a clear starting point for investigating a class or method, but if a quick read through relevant documentation isn’t enough, an even better approach is going to the source code. Narrow the project down to the right version and find the file which defines the code you need to understand. Assess what it does and what it needs, and compare how you’re using it. It may show you what you’re doing wrong, or a more efficient way to achieve something you’re overcomplicating.

Better still, keeping a local copy of your major dependencies lets you treat it as you should – parts of your own software. At Made we use Spree as the base of most of our e-Commerce projects, and by cloning the version or commit a project uses you get write access to its source. It stops being external to your own code. Obviously you should rarely use a fork outside of your development environment, but quickly swapping your gem reference over to a local copy is great for introspection. It’s your code anyway; now, investigating how something works in the context of your app as a whole can be as simple as dropping a ‘puts’ in the right place.

Plus, having it on your system lets you search it as easily as you do your own code. In an app which relies on two frameworks as large as Spree and Rails, a huge amount of the code that makes it to your server will be code you or your team didn’t write. Being informed about what it is doing underneath will improve your understanding on how to use it, and regularly searching through it is key.

Ask for help

This isn’t the last step, it should often be the first and is essential.

I’m a bit of a control freak about my own projects, and it shows when I talk about them. If you ask me about any function, I can tell you what it’s for, why it works the way it does and challenges I had writing it. And of course I know the pain points. As developers we spend hours working on even small features in our programs, and ultimately come to know everything about them.

This makes your teammates the most valuable sources of information you have. If you work in small teams like we do at Made, asking anyone on the project will usually yield valuable advice. They may have seen certain errors before, or have a good idea where it might be coming from. Even if they’re as lost as you, they know the code better and can give you a place to start.

When it comes to adding new features, asking for similar code already in the project can teach you common company practices and important decisions which have been made in a project. Plus they can prevent you from making mistakes which have already been made. Don’t worry about your ego, your collegues are there to help. Get as much info as you can before starting a new task, you’ll accomplish it faster and get used to the app quicker.

At the end of the day, trying to understand the inner mechanics of a new project is always hard. Whether you’re onboarding at a new company or contributing to open source, it takes time to become familiar with code patterns, structure, even issues that haven’t been fixed yet.

You’ll be a tourist for a while, look around and ask questions. The more you do, the sooner you can act like a local.

About the Author