Navigating a New Codebase: Tips and tricks for getting up to speed quickly

Note from Ray: This is a brand new tutorial released as part of the iOS 8 Feast. Enjoy!

Learning a new codebase can be a daunting task. There are typically many, many parts in any codebase and it can feel overwhelming to understand how everything fits together. After reading this tutorial you’ll be navigating a new codebase effectively.

This tutorial shows you how to expedite the process by offering a selection of techniques that help you associate what you see on the screen with what’s happening in the code. These tricks all have the same goal but work in different ways; you’ll learn how to choose the right tool for the job.

Since this tutorial works with a real-world codebase for an app currently in the App Store, it includes no Swift files. You can take a break from the onslaught of Swift articles out there and work with some Objective-C for a little while.

Getting Started

In this tutorial you’ll take on the role of a new hire at Wikipedia, who has a few tickets to address, which are challenges to fix bugs or implement feature requests.

You’ll working with the iOS Wikipedia App, which is an open source repo. This tutorial uses a forked copy which can be found here.

Don’t download a zipped version of the repo; instead, clone it using using your favorite git application or Terminal. If you aren’t familiar how to clone a repo, enter the commands below in Terminal, one at a time:

$ mkdir WikipediaApp 
$ cd WikipediApp
$ git clone git@github.com:DerekSelander/apps-ios-wikipedia.git
$ cd apps-ios-wikipedia
$ open Wikipedia.xcodeproj

Make sure you’re on the master branch — this should be selected by default. To do this, first run the following command:

$ git branch

Check in the output that the asterisk is next to master. It should look like this:

* master

If it is not, then run the following command:

$ git checkout master

Re-check that you’re on the master branch after running this if you wish!

Your first task when learning a new codebase has little to do with the code itself — instead, you should learn how the app is structured and how it functions.

Exploring the App

Open the app in Xcode and run it up in a simulator. Without looking at the code, work your way through the app and discover how to navigate to each of the screens shown below:

You’re really just trying to get a feel for how the app functions and how a user would experience the app. While you’re navigating around the app, ask yourself the following questions:

• How many distinct screens are in the app?
• If you had to name the screens, what would you name them?
• How complex are the screens; that is, how many different kinds of UI controls does the app use?
• Which screen uses the greatest variety of controls?
• What is the navigational flow that connects one screen to another?
• Which UI controls and navigation mechanisms are standard to iOS, and which ones appear to be custom or unfamiliar?

The point of these questions is not to answer them all at once. Asking these questions helps you notice far more about the app than if you just absentmindedly swiped through the screens. Exercises like this help you quickly build a mental model of the app based on its visible features such as interface components and UI behaviors.

To complete your mental model, you’ll need to link the visible features of the app to the invisible features of this app — that is, the codebase itself — by investigating the app’s classes, images, and other code-level resources.

Since a real production app like Wikipedia can easily involve hundreds of files, it’s essential to master the Xcode features that let you navigate quickly through the codebase. Otherwise, it’s like trying to learn your way around a new city by crawling around on your hands and knees, examining the streets with a magnifying glass! :]

Navigating around Xcode

Here’s a quick refresher on Xcode’s navigation features:

• To jump to the location of a method or property definition: ⌘+Click the item with the mouse, or place the cursor somewhere inside the method name and press Ctrl+⌘+J using the keyboard alone.
• To jump back to where you were, press Ctrl+2 to show the previous history list and choose the first item in the list. An even shorter key combo is Ctrl+⌘+left or a three finger swipe, provided you haven’t already dedicated those shortcuts to Mission Control. This is configurable via System Preferences / Keyboard.
• Want to find the corresponding Nib/Storyboard file for the current UIViewController? Press Ctrl+1, type User Interface and press Return and then Return again. This is a killer shortcut if you need to know whether the view controller was implemented directly in the code or via Interface Builder. In addition, if you hold option while opening the file, then it opens in the assistant editor.
• To jump to a particular filename method, press ⌘+Shift+O and type the name of the item you’re looking for.
• To get a bird’s-eye view of all the methods in a file, press Ctrl+6 to bring up a list of all the methods (as shown in the image below), then begin typing to narrow the selection.
• To jump to a specific line number, press ⌘+L and the line number.

For more tips and tricks with Xcode, check out the Supercharging Your Xcode Efficiency tutorial.

It’s time to get down and dirty with the codebase — the most logical place to start is with the various screens of the app and their associated UIViewControllers.