Create, Push, and Present Any View Controller in 1 LOC using Metaprogramming

Aug 15 · 9 min read

Eliminate boilerplate with Sourcery

Illustration by Jenya Hitz

TL;DR

We make view controller instantiation more type-safe by eliminating string IDs and use metaprogramming to generate functions that let you create, push, and present every view controller in 1 LOC, so you can save ~15 LOC whenever you want to perform push or present. It works both with storyboard-based view controllers and code-only ones. Here is the full source code example.


Foreword

Despite the recent announcement of SwiftUI, which is targeting iOS13, the traditional UIKit workflow will stick with us for a while. I would like to share our approach to dealing with boilerplate code for UIViewController instantiation and navigation.

Motivation

Storyboards are great when you need to design the appearance of your screen. They are not so great when it comes to writing code required for view controller instantiation or setting up transitions via segue mechanism, especially when you need to

  • change the existing screen sequence,
  • implement dynamic screen sequence,
  • instantiate an array of view controllers.

Here is the vanilla approach to dealing with view controller instantiation, setting up its parameters, and pushing onto the navigation stack:

There are several problems with this approach.

Strings as identifiers

Since both storyboard and view controller are accessed by string IDs ("MyStoryboard" and "MyViewController"), you can simply misspell them and get no compile-time error at all. For example, you could change the storyboard’s file name and forget to change corresponding string IDs in every call of UIStoryboard(name: "MyStoryboard", bundle: nil), and no compile-time error will occur.

Non-atomic instantiation

By non-atomic, I mean that a view controller is not instantiated by a single function call. In order to have a fully functional view controller you’ll have to do these steps:

  1. Instantiate view controller from storyboard,
  2. Setup parameters that are known at instantiation time,
  3. Setup parameters that are known at prepare-for-segue time.

Hence the full setup process is spread across several files, that leads us to a plethora of problems:

  • you might forget to do any of these steps and still get no compilation error,
  • you might copy and paste only 2 of the 3 required steps and still get no compilation error,
  • making any changes (e.g., adding to the view controller a new parameter known at prepare-for-segue time) has to be done in every prepare(for:sender:) implementation, and if you forget — you know what? You don’t get a compilation error!

All these situations will silently leave you with a half-initialized view controller, which is a splendid thing to discover at runtime.

Lots of boilerplate and code duplication

It costs us ~15 LOC for view controller instantiation, preparing for a segue, and pushing a view controller onto the navigation stack. It’s just annoying to repeat those 15 lines in any other place that leads to your view controller. It should be only 1 LOC.

Solution

Over the years we have shifted to the “design in a storyboard, compose in code” approach. We do not use segues for transitioning between screens, hence we do not pass parameters between screens in prepare(for:sender:). Instead, we do our design in a storyboard and instantiate, compose, and route the screens in code.

Another important aspect of our programming approach is to move as much of runtime errors to compile-time as possible, so we could get closer to the holy grail of the “if no errors at build time, then no errors at runtime” paradigm.

There are many possible types of errors that might occur at runtime. There are not so many mechanics to detect and prevent those runtime errors at the build time. There is one tool at our disposal that flawlessly works at the build time — the type system. Hence we try to express our runtime problems as compile-time type problems in order to prevent runtime errors by getting compile-time errors. Let the compiler help you.

We will modify our vanilla example in 5 easy steps:

  1. Eliminate String Identifiers
  2. Make Instantiation Atomic
  3. Create 1 LOC Navigation
  4. Eliminate Boilerplate with Metaprogramming
  5. Add Resource Consistency Tests using Metaprogramming

Eliminate String Identifiers

Let’s get rid of those string identifiers. Instead of

… we will write

We assume that view controller’s Storyboard ID is equal to its type name.

UIViewController.instantiate is a utility function. It creates a view controller and casts it to the specified type, hence the client doesn’t have to write cast herself.

UIStoryboard.Name is a project-specific enum:

If you misspell the storyboard name when calling UIViewController.instantiate, then it just won’t compile. If you type the wrong view controller type name, then it just won’t compile. Type system to the rescue!

This approach is not persistent to changes of a storyboard file name or changes of a view controller type name. In order to guarantee correct naming at runtime, we generate resource consistency tests. We will cover this later in the corresponding section.

Make Instantiation Atomic

Since we want our view controllers to be instantiated by a single function call we completely drop segues, and instead of this:

… we write

For each view controller, there is a createMyViewController function that takes all parameters required for the view controller to be 100% initialized and operational.

We oblige all our view controllers to implement an initialize function that takes all parameters required for this view controller:

Hence the createMyViewController function will look like this:

The initialize should only be called once and only by a create function.

The initialize is written by hand, but createMyViewController is generated by a metaprogramming template. We will discuss code generation later.

Now we have an atomic instantiation of our view controller provided by createMyViewController functions. These functions are safer for copy-pasting since you can’t copy half of a function call and deal with a half-initialized view controller as a result.

If you forget to pass some parameters to createMyViewController function, then the compiler will be happy to let you know. Once again, type system to the rescue!

Create 1 LOC Navigation

Now that we have createMyViewController, we want to push or present our view controller. In many cases we create a view controller only to pass it to the navigation controller:

It would be much nicer if we could just write:

For each view controller, we have pushMyViewController and presentMyViewController, which are generated by a metaprogramming template that will be discussed later in the corresponding section.

Don’t Pollute the Global Namespace

If you work on a moderate-size project, then you are probably going to have 50+ screens. That means that you will have 50+ create, 50+ push, and 50+ present functions generated for you. Since we don’t want to pollute the global namespace with these functions, we need a place to store all these functions. Where do we put them?

A hint might be found in the essay Learnable Programming by Bret Victor, where he writes:

Strangely, I don’t actually know of any APIs that are intentionally designed with autocomplete in mind.

We are going to fix that. This is how our create functions will look like:

The implementation is trivial:

Same for navigation, we will write our push and present functions just like this:

This implementation is a bit different since we want our functions to be called on an instance of UINavigationController (in case of push) and on an instance of UIViewController (in case of present):

We have just added a single extension property to UINavigationController class and 2 extension properties to UIViewController. Each of those extension properties has 50+ functions.

And this is how our autocomplete suggestions look like now:

Eliminate Boilerplate with Metaprogramming

Now that we have designed our APIs we can generate the code. For each view controller in our project, we are going to generate 3 functions: create, push, and present. We are going to generate code with Sourcery — a tool developed by Krzysztof Zabłocki.

You provide a template file, Sourcery parses your source code and generates code based on your template and the parsed source code. Sourcery can be used as a standalone executable or embedded right into the Xcode building process as a Run Script phase. It automatically regenerates code on any changes in your template file or in the project source files.

We write our templates in Swift. Sourcery’s API is way richer than Swift’s native reflection. You can iterate over types presented in your project, filter them, and access all their functions, variable names, template arguments and so on. This is how you iterate over all view controllers that have an initialize method:

The functions to be generated — create, push, and present, — have almost the same signature as initialize, the only difference is the animated parameter in the latter two:

In our Sourcery template, we iterate over all view controllers, look at their initialize methods, and replicate the same signature in create, push, and present and add an animated parameter at the end of push and present. If a view controller doesn’t need parameters to be set and hence doesn’t have an initialize method, then its create function will not have parameters, and push and present will get only the animated parameter.

There is one more thing to be considered regarding the create function. We need to know UIStoryboard.Name for those view controllers that are instantiated from a storyboard. We make all such view controllers conform to StoryboardInstantiatable protocol:

We could use Sourcery annotations to specify the UIStoryboard.Name, but it wouldn’t work with the Xcode refactoring tool when we need to rename those UIStoryboard.Name cases.

This is how MyViewController conforms to StoryboardInstantiatable protocol:

It is extremely valuable when you want to add a new parameter to the initialize function and those changes are instantly reflected in create, push, and present, since Sourcery automatically regenerates them after every change of initialize. No need to manually forward a new parameter to 3 functions!

Add Resource Consistency Tests using Metaprogramming

Now that we have dropped string identifiers, the instantiation of a storyboard-based view controller looks like this:

If a storyboard file name or a view controller type name is changed, then the compile-time error will not occur. If we can’t catch errors at compile-time, then we catch them at test time. Once again Sourcery comes to the rescue. In order to guarantee the correct naming of all related resources (storyboard file names, view controllers’ storyboard IDs), we generate resource consistency tests.

There are 2 groups of these tests: storyboard tests and view controller tests.

Storyboard tests are intended to check whether every case from UIStoryboard.Name enum successfully loads a storyboard by its rawValue. Here is an example of such a test for one case:

View controller tests are intended to check whether every view controller that conforms to StoryboardInstantiatable protocol can be instantiated from its storyboard (their type names must equal their Storyboard IDs). Here is an example of such a test:

It is important to say that there is an elegant solution to the resource consistency problem that we haven’t adapted yet. Instead of testing raw values of UIStoryboard.Name cases, we could just generate the UIStoryboard.Name enum. Please refer to SwiftGen for the details.

Discussion

In order to eliminate error-prone and boilerplate code, we have developed a type-safe solution using metaprogramming. We don’t pollute the global namespace and design our API with autocomplete in mind. In every place where you want to push a view controller, instead of 15 LOC now you can write only 1:

The less code, the more opportunities for new pattern discovery and further improvements.

For the sake of simplicity, we have been working with vanilla UINavigationController. The presented metaprogramming approach can be adapted to more sophisticated navigation architectures, such as coordinators, and other forms of user interaction such as 3D Touch.

We prefer functional programming over object-oriented, that’s why UIViewController multilevel inheritance is not supported in our templates.

One of the drawbacks of our approach is that initialize is not a private method. If we want to have our view controller in one file and all generated code in another, then we can’t make the initialize function private since createMyViewController must access initialize. At the same time, Sourcery supports inlining generated code right into the source files instead of separate files, but we just don’t even want to look at this boilerplate while programming our view controllers. Therefore, there is a tacit convention: “don’t manually call an initialize method”; luckily, our programmers are intelligent enough to follow it.

The full example Xcode project with a typical project structure including all discussed Sourcery templates can be found here.


Acknowledgments

I would like to thank Dmitry Cherednikov and Vyacheslav Shakaev for their constructive criticism and valuable comments on the draft version of this text. I would also like to thank Michael Goremykin for his contribution to the templates’ source code.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade