Create, Push, and Present Any View Controller in 1 LOC using Metaprogramming
Eliminate boilerplate with Sourcery
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.
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.
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 (
"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.
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:
- Instantiate view controller from storyboard,
- Setup parameters that are known at instantiation time,
- 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.
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:
- Eliminate String Identifiers
- Make Instantiation Atomic
- Create 1 LOC Navigation
- Eliminate Boilerplate with Metaprogramming
- 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:
createMyViewController function will look like this:
initialize should only be called once and only by a
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
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+
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?
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
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
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:
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
The functions to be generated —
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
present and add an
animated parameter at the end of
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
present will get only the
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
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
This is how
MyViewController conforms to
It is extremely valuable when you want to add a new parameter to the
initialize function and those changes are instantly reflected in
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.
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.
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.