Doing things at the right level is very important for long-term, sustainable programming. One theme of this blog is how to beat Massive View Controller. Massive View Controller happens because you’re doing things on the wrong level. Things in the model layer, like values and enumerations, bubble “up” to the view controller, while organizational responsibilities, like coordination, bubble “down” to the view controller. The combined complexity of all this code makes the view controller become tangled with itself and impossible to grok.
What do I mean by “the right level”? Let’s dive in.
The Knight’s Template Method
If you have one thing, and you want to make another thing, using inheritance to solve that problem will always put you in a bind. I talked about sidestepping inheritance for share code in last week’s Prefer Composition to Inheritance. This week I’d like to talk about when the extenuating factors win out, and you have to use inheritance.
If you subclass from one thing to make another thing, you’re failing to keep things on the right level. To maintain order in your code, remember: you can’t have just one specialization. In this case, you have three things: the shared code, which goes in a superclass; and the two branches of differing code, which are the specialized subclasses.
This type of structure creates two levels. The top level, the superclass, contains the abstraction, the prototype for the concept; it shouldn’t be instantiated. The bottom level contains the concretion, the congealed form of the ideas; it can’t exist without the upper level. This is the Template Method pattern. It’s probably an anti-pattern. Nevertheless, when you have to do it, do it right.
Color-coded
All modern editors use color to signify meaning. Constants are one color, methods another, local variables a third. This highlighting is designed to help readers parse code more easily, by allowing the user to focus on chunks like literals or instance variables at once. One new way I’ve learned to use syntax highlighting is called the squint test, and it’s a litmus test for the clustering of code.
The squint test is simple: squint at your code, and make sure similar colors sit together. If they don’t, you might not be doing things on the right level. In its simplest form, it will compel you to move string literals to the top of a file. You can use it for much more, though. The squint test can also help you separate the semantic components of your class that are related. In this talk, Sandi Metz refactors the Gilded Rose kata, and when we squint at the product of her refactoring, it’s clear that the right-hand side of the slide is better separated and better factored.
N.B.: you’d be forgiven for thinking she needs to refactor this more. She does, and her final result is awesome. I highly recommend the talk. Even better, try the kata out before you watch the talk.
At C level
Objective-C is designed as a layer on top of C. It can do everything that C can do, and then some. You could ship an iOS app written entirely in C or C++ if you wanted. This interoperability has been a boon to developers, allowing them to use a vast array of libraries in their apps that were never intended for use in Objective-C.
However, it’s also provided confusion to developers writing code. Should this simple string transformation be in a category on NSString or a C function that takes one string parameter? A category incurs the cost of an objc_msgSend, but dipping down to the C level incurs a context switch for the reader of the code.
When I’m reading C code in an app, I wonder what dropping to C means, semantically. Does it mean that the code needed to be more performant or that the author was more comfortable writing C than Objective-C? What should I infer from the switch? Staying consistent and using one language prevents these questions from being asked; also, staying consistent in your basis for dropping down to C guides your reader into inferring more meaning from your code.
Preprocessor macros are similar. They have a ton of value in providing code generation and metaprogramming to more static languages, but they incur a context-switching cost as well. Worse still, macro code doesn’t get highlighted and there’s a bunch of slashes everywhere, making it hard to read. Do string literals need to go in a #define, or can they be class or instance methods in an Objective-C class?
In the latest version of the Genius app, we support annotating other websites. As you can imagine, this requires calling a lot of JavaScript from within Objective-C. All of this JavaScript is inside NSString literals, which, like preprocessor macros, have no syntax highlighting. To alleviate this as much as possible, the JavaScript is clustered together in the same object, and hidden behind a type-safe Objective-C interface. If you need to mess with the JavaScript, there’s one .m file to go to. No more grepping for stringByEvaluatingJavaScriptFromString:.
Staying on the right level helps keep your code legible to not only your teammates but also future versions of yourself.
Layer cake
Your app is composed of several layers: data storage, manipulation, presentation, and so on. The more clearly the layers are defined, the more obvious it is when code from one level bleeds over into another level. Unfortunately, we’re stuck with the ill-defined and meaningless name Controller, and we have to work with it. Presentation code might go into the controller at first. But as it gets more and more bulky, it can split into its own layer, like a cell undergoing mitosis. This new, well-defined layer should have less trouble keeping out-of-scope responsibilities out and keeping its role clear.
Wrapping up
These examples seek to show two things: 1. working at the wrong level makes your code more complex and hard to understand, and 2. working at the right level smoothes out your code and keeps it easy to maintain.
However, keeping your code neatly organized in these ways requires rigor. No amount of automated testing or static analysis will reveal that your code is poorly structured. Well-crafted programs come from the human element. Meticulous planning and code review help you critically analyze the code until it satisfies you.
In the beginning, there was CGRectMake. It was hideous.
_badge.frame = CGRectMake((self.frame.size.width - (widthOfBadge))/2,
imageViewSize + 5,
widthOfBadge,
sizeOfText.height);
Autoresizing masks sometimes helped, but they weren’t as flexible as their names suggested.
_imageView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
(This is all real code. Instance variables have been changed to protect the innocent.)
As more programs were written, techniques were discovered to abstract away some of the mess. But it was still procedural C, and it was still kinda hard to read.
Then came Auto Layout. Auto Layout is slow, confusing, and verbose. But it’s declarative, and it solves a system of equations every time it lays out your code, which is just plain cool.
These are all layout abstractions, but none of them are great. What do we want out of a great layout abstraction?
We want it to be code. Interface Builder is an impressive tool that gets more impressive with every release. But it’s fundamentally not as expressive as code, doesn’t play well with source control, and generates components that aren’t reusable (we can’t conditionally apply a layout to a view, for example).
We want it to be fast. We’re dealing with primitive numbers here. There’s no reason calculations should take a long time.
We want it to be simple. You should be able to glance at it and tell what the layout looks like. The code should be concise and straightforward.
We want it to be expressive. You should be able to describe any layout with the abstraction.
The abstraction should be very malleable. Easy things should be easy, and hard things should be possible.
Since no layout abstraction can satisfy all of these criteria, we’re making a trade-off with any solution that we pick. Auto Layout trades speed and simplicity for the ability to be expressed in Interface Builder. Anyone who’s tried to set up constraints in code knows how painful using even the visual format language can be. Libraries like CompactConstraint or Cartography can help with the verbosity of Auto Layout, but the point I want to press here is that Auto Layout isn’t the ultimate form of expressing layouts.
Even though Apple engineers have been subtly and not-so-subtly pushing us towards Auto Layout since it was released, and maybe one day we won’t be allowed to use anything but Auto Layout, computers are Turing-complete. You don’t have to wait for anyone: write your own future.
For me, the most natural way to think about it is that views should have a layout, the same way they have subviews. You could hot-swap this layout for lots of reasons: to perform an animation, present the same views on different devices, or A/B test different layouts. If your view is HTML markup, your layout object would be the CSS.
Maybe you like the rectangle-slicing CGRectDivide model of layout. What would that look like if it were an object, instead of a procedure? Can it be more than just C functions that are called sequentially? Does our RectDivider object have access to the class of its target view? Can it use names instead when applying rects to subviews, to reduce coupling?
Or maybe you like Java’s configurable Layout Managers. Layout Managers let you pick a strategy, like “fill”, or “stack”, or “grid”, and pass in a list of views which will have that layout strategy applied to them. Here’s an exploration of them in iOS, and here’s a library that approaches layout managers in a slightly different way.
Or maybe you like CSS’s flexbox. Flexbox is a new CSS display style that not all browsers have implemented yet. It lays out views in a row (either horizontal or vertical) and lets you assign which subviews have fixed width (or height), and which subviews should be stretched out to fill the view. You can imagine how powerful this can be when coupled with a scroll view.
What do I want? Sometimes I just want to write an object and have the layout engine just figure out what to do:
@implementation SKUserCellLayoutSpecification
- (CGFloat)imageViewDimension {
return self.height;
}
- (CGSize)sizeForImageView {
return CGSizeMake(self.imageViewDimension, self.imageViewDimension);
}
- (CGPoint)originForLabel {
return CGPointMake(0, self.imageViewDimension);
}
- (CGFloat)widthForLabel {
return self.width - self.imageViewDimension;
}
- (CGFloat)heightForLabel {
return self.height;
}
@end
Maybe something this abstract could finally prevent us from having to write our layout code twice: once in -sizeThatFits: and once in -layoutSubviews.
But most of the time I just want to pick between them all. I want a protocol that every layout conforms to, and I want to be able to swap between them at will. Maybe some of the concrete implementations are backed with Auto Layout, and others with a layout manager. You’d finally be able to pick the right tool for the job. And that seems like a future worth writing.
Further exploration
There are a few places where I drew inspiration for this post, in order of age:
Colin T.A. Gray, who worked on MotionKit, a part of RubyMotion, uses Layout objects to push everything down from the view controller, not just for positioning views. Nevertheless, his library provides a cool (Ruby) DSL for adding constraints and fetching frames. He gave a talk on MotionKit in 2014, which you can find here (direct link to 13:47).
Facebook’s Paper uses two abstractions, Metrics and LayoutSpec. You can see more in their tech talk, Building Paper (direct link to 20:55). This is a pretty cool structure, and they separate calculation of their rects from their application, solving the
-sizeThatFits:/-layoutSubviewsproblem. Their LayoutSpecs can also be defined in JSON, meaning their designers can write them and check them in, with no help from engineers.Facebook’s React Native has a reimplementation of Flexbox for use in their Javascript app engine. You can find out more in the React Native Keynote (direct link to 13:07). While it’s probably designed for use only in their JS framework, it would be awesome if we could even apply it to arbitrary UIViews.
Josh Abernathy’s SwiftBox is an implementation of FlexBox for Swift.
There’s a lot that I want to say about composition and inheritance, but Sandi Metz covers the basics better than I can in Nothing is Something. So, since she already covered why inheritance will fail you, I will explore a few techniques we can use to avoid it.
Interior Decorating
Let’s imagine a new networking library. Network requests are defined by template objects that conform to a protocol:
@protocol SKRequestTemplate
@property (readonly) NSURL *baseURL;
@optional
@property (readonly) NSString *method;
@property (readonly) NSString *path;
@property (readonly) NSDictionary *parameters;
@property (readonly) NSDictionary *headers;
@end
With this design, we’re given a lot of flexibilty in how we define our request templates, and we can rely on some other component to convert each template into an NSURLRequest, and that request can be fired by some other uninteresting machinery. To create the request, we need to grab each property from the template in turn.
//...
mutableURLRequest.HTTPMethod = [template method]
//...
When we go to use these templates however, we notice that we can’t have any default behavior. Since it’s using a protocol and not inheritance, we can’t use the superclass to set the default method to GET. We can avoid this with a nil-coalescer:
//...
mutableURLRequest.HTTPMethod = [template method] ?: @"GET";
//...
We run this code and realize that we have an even bigger problem. If there’s no implementation defined for -method, our template is going to blow up! We can do something ugly like:
//...
mutableURLRequest.HTTPMethod = [template respondsToSelector:@selector(method)] ? [template method] : @"GET";
//...
But this is inelegant and we wish we could just force our users to subclass something so that we can hide this behavior away. But don’t fret! We have options outside of inheritance. To add behavior in a composition-friendly way, we use the Decorator pattern. Let’s define something called a SafeTemplate:
@interface SKSafeRequestTemplate : NSObject
- (instancetype)initWithUnsafeTemplate:(id)unsafeTemplate;
@property (nonatomic, readonly) id unsafeTemplate;
@property (readonly) NSURL *baseURL;
@property (readonly) NSString *method;
@property (readonly) NSString *path;
@property (readonly) NSDictionary *parameters;
@property (readonly) NSDictionary *headers;
@end
We can now pass our “unsafeTemplate” into this object, and for each property, it wraps the execution in a check, and can return any default we choose:
- (NSString *)method {
if ([self.unsafeTemplate respondsToSelector:@selector(method)]) {
return [self.unsafeTemplate method];
}
return @"GET";
}
//...
URLRequest.HTTPMethod = [safeTemplate method];
//...
A particularly elegant note on this solution: the wrapper itself doesn’t conform to SKRequestTemplate, even though its parameter does. This means that if we add a new method to the protocol and try to use it from the safe template, the compiler will groan at us. It must be defined on the safe template before we can use it, and we’ll be reminded to add it there as well. Normally, with inheritance, your “contract” with the outside world includes all of your superclass’s methods; with decoration, you only have to provide what you say you’ll provide. Aaron Patterson documents a case where the rails/core team got bitten by this exact problem.
The Presenter pattern that I outline in 8 Patterns to Help You Destroy Massive View Controller is a more specific version of this technique. Value Objects are also really just a decorator around something like a string or a number.
And that’s the Decorator pattern. It’s very flexible, very useful, and a great weapon in the war on inheritance.
Strategery
One awesome thing that Sandi said is “There’s no such thing as one specialization. If you’re specializing something, you have two things.” This was a revelation for me.
Let’s continue to work with our networking library. Using the data source pattern from 8 Patterns to Help You Destroy Massive View Controller, let’s make an object called SKRemoteDataSource, which fetches a collection of objects from an API for display in table view.
@interface SKRemoteDataSource : NSObject
@property (nonatomic, weak) id delegate;
@property (readonly) NSUInteger numberOfSections;
- (NSUInteger) numberOfObjectsInSection:(NSUInteger)section;
- (id) objectAtIndexPath:(NSIndexPath*)indexPath;
- (void)fetchData;
@property (nonatomic) NSURL *URL;
@property (nonatomic) NSDictionary *queryParameters;
@property (nonatomic) NSString *keyPath;
@end
This is a very useful class, but sometimes the remote objects are paginated. So we could subclass SKRemoteDataSource and make SKPaginatedDataSource. Hey, pagination is just a special case of a remote data source, right?
@interface SKPaginatedDataSource : SKRemoteDataSource
@property (nonatomic, readonly) NSInteger currentPage;
@property (nonatomic, readonly) NSInteger numberOfPages;
@property (nonatomic, readonly) BOOL hasMorePages;
- (void)fetchNextPage;
@end
While this seems reasonable, every change you make to the superclass will break the subclass. I can tell you this because I’ve written this exact code in this exact way before.
What I had was a bad version of the Template Method pattern. To implement the template method properly, you need to:
create a superclass with all common behavior
throw an exception from the superclass for all differing behavior
and make your two subclasses (because you can never have one specialization!) and override the points of difference
Even properly implemented, however, the Template Method pattern is probably an anti-pattern. It’s based on inheritance which will always strongly couple your components together. Fortunately, we have an alternative, which is based on composition.
We have two responsibilities here: downloading an array of items from an API, and presenting them as a data source. These two responsbilities have been tightly coupled together. Extracting the shared core will make simpler objects that can be used more often. When we wrap behavior in an object and inject it into other objects, it’s known as the Strategy pattern.
The final solution was SKCollectionFetcher, which downloaded a collection of objects from an API. The paginated and regular remote data sources each had a collection fetcher, and the logic was no longer duplicated.
@interface SKCollectionFetcher : NSObject
@property (nonatomic, strong) NSURL *URL;
@property (nonatomic, strong) NSDictionary *queryParameters;
@property (nonatomic, strong) NSString *keyPath;
- (void)fetchCollectionWithSuccessBlock:(void (^)(NSArray *objects))successBlock failureBlock:(void (^)(NSError *error))failureBlock;
- (void)cancelCurrentFetch;
@end
@interface SKRemoteDataSource : NSObject
@property (nonatomic, weak) id delegate;
@property (nonatomic, assign, readonly) NSUInteger numberOfSections;
- (NSUInteger) numberOfObjectsInSection:(NSUInteger)section;
- (id) objectAtIndexPath:(NSIndexPath*)indexPath;
- (void)fetchData;
@property (nonatomic, strong) SKCollectionFetcher *collectionFetcher;
@end
Since the data source and the collection fetcher are now separated, we can swap them out at will. In some cases, we’ll need a slightly different collection fetcher, and that will work with our remote data source. In other cases, the reverse will be true, and we’ll need a slightly different data source. For example, if we need relative pagination, which is based on timestamps, we can write a new data source while using the old collection fetcher. Writing code with composition makes this sort of flexibilty possible.
-[NSString containsString:] was added in iOS 8. If you’re writing a standard library, this seems like one of the most crucial components for string handling. And yet, it’s been conspicuously absent since the early ’90s, when NSString was created.
Apple gives you a function called -rangeOfString: whose functionality is a superset of this behavior. You can use a short snippet of code with -rangeOfString: in the place of -containsString: :
if ([aString rangeOfString:searchString].location != NSNotFound) {
//substring is found
} else {
//substring is not present
}
Writing it this way is very tough to read, and code is read much more often than it is written. “The location of the searchString inside aString is not equal to ‘not found’” is a tough thing to parse from code to English, especially because of the double negative.
Of course, you’re currently screaming at me, “Just use a category!” And it’s trivial to add this method to the NSString class. I can do it, and you can too.
- (BOOL)containsString:(NSString *)searchString {
return [self rangeOfString:searchString].location != NSNotFound;
}
This is an unsatisfactory solution. There are three primary reasons why.
First, developers are lazy. If you search GitHub for rangeOfString , you will find pages and pages of open source repositories that use -rangeOfString almost exclusively in the place of -containsString:. Why didn’t they just write the category for the message they needed? There’s a lot of cognitive load to adding a file to your project. It also involves a context switch: instead of just writing the code you want in the place where you want it, you have to jump to a different place to add a different thing. The out-of-order nature of that kind of programming makes it very hard to do the right thing.
Secondly, category methods must either be prefixed — and ugly — or unprefixed — and go against Apple’s best practices. Personally, I see prefixing as unnecessary. How many ways are there to write -containsString: ? How many ways are there to write -firstObject ? Nevertheless, I worry about method names -select: that could easily conflict (imagine a method that selects objects in a collection based on a block, like Ruby’s Enumerable #select, or an IBAction routed through the responder chain, like -copy: or -selectAll: ). The important thing here is that, whether or not I think prefixing is ugly, I also don’t like going against best practices. There isn’t really a way out of this trap. My code will be unsatisfactory either way.
Lastly, writing the method yourself in a category will always be less performant than the vendor’s version. While I was writing my library Objective-Shorthand, I did some research in the runtime on -[NSArray reversedArray]. I found that even though it’s not a public method, the SDK does actually respond to this message. It returns an __NSArrayReversed, which is ostensibly an class-clustered NSArray that accesses objects in reverse order. Most implementations of array reversing (including mine!) would call allObjects on the reverseObjectEnumerator, which creates a full copy of the array, the obvious and simple solution. Apple’s implementation cleverly sidesteps this. You could imagine similar optimizations for other methods. Why this method isn’t public, I don’t know.
In using categories, the best we can do is bundle up all these obvious shortcomings into a single library, and use that one dependency. This is exactly what Objective-Shorthand attempts to do. And even in this “best” solution, we still have to import Objective-Shorthand everywhere we need it, or include it in the .pch file (which is probably an anti-pattern, since it makes your dependencies implicit).
There are other reasons as well why the bundling of all these categories together doesn’t work. I did a quick proof-of-concept for a small state machine library a few weeks ago, and while Objective-Shorthand would have made my work a lot easier, I couldn’t justify making other developers dependent on Objective-Shorthand, just to make my coding experience a little nicer.
So given these myriad reasons why categories aren’t good enough, why will Apple not implement these methods? One common reasoning I’ve heard is that Apple’s conservatism causes a reticence for API additions. Mattt Thompson asked an engineer at a WWDC lab why it took so long to add JSON support to the SDK:
Apple is a company with a long view of technology. It’s really difficult to tell whether a technology like JSON is going to stick, or if it’s just another fad. Apple once released a framework for PubSub, which despite not being widely known or used, still has to be supported for the foreseeable future. Each technology is a gamble of engineering resources.
This argument isn’t very compelling! -containsString: isn’t a new technology, nor is its usage in doubt. Our simple GitHub search from earlier shows that. Also, don’t forget that this is the same vendor that added a dozen methods to NSString for manipulating paths. Conservative? Doubtful!
Other vendors have proven that it’s possible to do this well. Ruby, for example, takes it to the other extreme: their Integer objects respond to methods like #odd?, #even? and even #gcd. Providing those methods in the standard library yields more readable code and it gives the vendor the opportunity to tweak and optimize them at later date, knowing that anyone who needs them will benefit from their optimizations.
All of the solutions available to developers — the unreadable -rangeOfString: dance, a utility object, small categories copied to each new project, or compiling them into one library like Objective-Shorthand — are insufficient.
In the same way that base types like Swift’s Optional or JavaScript ES6’s Promises must be built-in for proper adoption, these simple methods need to be available to all developers. Apple’s proclivity towards leaving holes in their API forces developers into a bind. We must either write inexpressive, hard-to-read code, do needless work opening these classes back up, or leave a trail of dependencies in our wake.
One of the biggest problems with the big view controllers is that they entangle your flow logic, view logic, and business logic.
When a table cell is selected, that delegate method typically looks like this:
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
id object = [self.dataSource objectAtIndexPath:indexPath];
SKDetailViewController *detailViewController = [[SKDetailViewController alloc] initWithDetailObject:object]
[self.navigationController presentViewController:detailViewController animated:YES];
}
Three simple lines: get the object; create a view controller; present the view controller. In a simple app, this works great. Each view controller is probably used once, and in only one context. Coupling them together like this isn’t a dangerous proposition. As your app grows in complexity, however, the same view controller might get used in a new way or in a new place. Maybe it’s on the iPad. Maybe it’s in an extension. Maybe it’s a new flow for doing an old thing.
If the flow logic is encoded into the view controller itself, the view controller can’t be reused for its stunningly good looks without dragging all that flow code with it. Don’t forget, the view controller base class is prefixed with UI. It’s view object, and handling user flow is out of its scope.
In the code example above, the view controller knows how to create the next thing in the flow, and how to present it. In the third line of code, it tells its parent view controller what to do, which definitely seems backwards. And even worse, that flow code is distributed among multiple view controllers, each of which only knows how to perform the next step.
I used to think of the view controllers as the highest level thing in app, the things that know how to run the whole show. Lately, however, I’ve found many advantages to having the view controllers be bossed around by an even higher level object, one whose role is to marshal and manage all the view controllers in its purview.
I call these objects Coordinators, but I’ve also heard them called Directors. To really execute this pattern well, you need one high-level coordinator that directs the whole app (this is sometimes known as the Application Controller pattern). The app delegate holds on to the AppCoordinator. Every coordinator holds an array of its child coordinators. Especially if you have more than one, as in a tab bar app, each navigation controller gets its own coordinator, for directing its behavior and flow. Further child coordinators can be created for specific tasks like signing up or creating content. Each coordinator is spawned by its parent coordinator. As always, use this pattern early in the development process, so they’re useful even in single-step tasks, such as authentication.
The Coordinator is a PONSO, like all great objects. For something like Instagram’s photo creation flow, we could have a PhotoCreationCoordinator. The app coordinator could spawn a new one, and pass it the root view controller so that it could present the first view controller in the flow.
- (void)beginPhotoCreationProcess {
PhotoCreationCoordinator *coordinator = [[PhotoCreationCoordinator alloc] initWithRootViewController:self.rootViewController delegate:self]
[self.childCoordinators addObject:coordinator];
[coordinator beginPhotoCreationProcess];
}
- (void)photoCreationCompletedSuccessfully:(PhotoCreationCoordinator *)coordinator {
[self.childCoordinators removeObject:coordinator];
}
- (void)photoCreationCanceled:(PhotoCreationCoordinator *)coordinator {
[self.childCoordinators removeObject:coordinator];
}
The coordinator’s -beginPhotoCreationProcess method can now create a new photo selection view controller and configure it as needed. The coordinator can conform to the photo selection view controller’s delegate so that it can be informed when it’s time to present the next step. None of the view controllers in the process need to know about any of the other view controllers. Each view controller is an island.
Business logic, like posting the photo, is wrapped up in its own object and can either be pushed up to the coordinator or pushed down to the model as appropriate. Either way, it comes out of the view controller. Moving it up is great because the coordinator is already acting as the glue between different parts of your code already.
The benefits to extracting the flow into a coordinator are myriad. View controllers now can focus on their goal of binding a model to a view. The can be reused more easily, such as in extensions or unbundled apps, without having complex conditionals to manage different contexts. A/B testing is as simple as creating a different coordinator object and using that to start the process. Flow logic now has a home, and things that have a home feel real nice.
View controller initialization is also extracted. This shouldn’t be overlooked. Initializing is always a more complex task than it seems, requiring lots of knowledge about classes and configuations, and we moved it to a better place where more informed decisions can be made.
Coordinator objects naturally fall into one of many disjoint states — in other words, especially for an iPhone app, only one screen is visible at any time. This makes them a ripe place to use state machines to manage all of the data in their custody.
Apple loves having the view controller be the center of the iOS world. This is obvious in the new UISplitViewController APIs in iOS 8, as well as Interface Builder components like storyboard segues. Unfortunately, a view controller-centric approach to app development isn’t scalable. The Coordinator is a great way to isolate your code into small, easily-replaced chunks, and another part of the solution to view controller malaise.
As awesome as state machines are, they can often be very high-ceremony to set up. A typical Objective-C library requires a lot of code to set up. I wanted to explore combining a few techniques from the this blog to try and make a low-ceremony state machine, one that doesn’t require setting up all of your states, transitions, and events ahead of time.
What does the interface for my library look like? Let’s take a simple state machine for a subway turnstile:
- (void)init {
self = [super init];
if (!self) return nil;
_stateMachine = [[SKStateMachine alloc] initWithInitialState:@"locked" delegate:self];
return self;
}
- (void)coinInserted:(id)sender {
[self.stateMachine transitionToState:@"unlocked"];
}
- (void)humanEntered:(id)sender {
[self.stateMachine transitionToState:@"locked"];
}
- (BOOL)isLocked {
return [self.stateMachine canTransitionToState:@"unlocked"];
}
- (void)transitionFromLockedToUnlocked {
//transition code
}
- (void)transitionFromUnlockedToLocked {
//transition code
}
That’s it. The library uses Dynamic Method Construction to call methods on the delegate, in the form of -transitionFromTo. If a method is defined, it’s a valid transition; if not, it throws an exception. You can find the code on GitHub.
I’d love to add a few things to it, like dynamic methods in the form of -transitionFrom and -transitionTo that are always called when entering or leaving a state (unless the transition is invalid). It would also be great to get some userInfo dictionaries passed around to store state, and maybe an optional loggingDelegate. I haven’t actually used the library yet, so I don’t want to add stuff until I figure out what works and what doesn’t.
The other technique I used to write this library is pure objects, which I’ve written about before on this blog. There are 4 classes in the library: SKStateMachine, SKSelectorConstructor, SKLlamaCaseConverter, and SKComponentSplitter. Each object is pure, requiring nothing but its initializer’s parameters and outputting immutable objects. I took the pure object pattern to its logical extreme. Every method in every object takes advantage of an instance variable. Almost every method has no parameters. It’s all messages. It’s a refreshing and fun way to write code, if a little exhausting. It’s readable, well-factored, and truly single-responsiblity.
Objective-C is an old language though, and it’s not designed for writing many short objects like these. What are the pain points? There are a few: writing headers is very annoying; writing initializers is very annoying; Objective-C’s policy of “no dot syntax unless it’s declared as a property” is absurd; the ceremony around lazy-loading is annoying. The good news is that Swift fixes all of these issues except the initializer issue. If I have some read-only properties and an initializer that takes properties with those names, can’t the compiler just write the body of that initializer for me? In fact, shouldn’t initializers be limited to only that behavior?
When Swift is more mature, it’ll be fun to write some of this code in a more modern language. The fundamental point of this project though, constructing selectors and calling them dynamically, isn’t possible in Swift. Swift removes message-passing, and thus a lot of dynamic features. I’m curious to see if the simple interface for defining transitions (just define a method!) will make it easier to use state machines in more places.
When writing object-oriented code, it’s often much easier to create the objects that store stuff rather than the objects that do stuff. Objects that keep some data and their associated actions are more natural than those that model a process over time. However, we still have to write these workflow objects, since they’ll encapsulate a lot of the business logic, flow logic, and complexity of our apps.
What makes writing a workflow object so tough is that it changes over time. This means that when you initialize an object that manages a workflow, you initialize it in an incomplete state. Some of the products of the workflow haven’t been calculated yet, by necessity. This means that instance variables start out set to nil, and slowly take values over time. Sometimes, those variables are for values that aren’t even products of the workflow! They’re just flags, representing how far into the process we are.
How many times have you written code like this?
- (void)performAPIRequest {
if (self.request) {
return;
}
self.request = [RequestFactory requestWith...
}
Here, self.request serves to assure that we don’t perform the API request more that once. It’s acting as a cheap, shitty version of state machine. The longer-lived and complex your process is, the worse this becomes. The absolute worst is when this code is the view controller, polluting it with instance variables that have nothing to do with the management of the view.
The solution is simple: upgrade your cheap, shitty state machine to a bona fide, grown-up state machine.
A state machine is a construct that can have several states and defines the transitions between those states that are valid. For example, the Initial state could transition to Loading, which could transition to Completed, Failed, or Cancelled. Other transitions would be invalid.
In the literature, state machines are sometimes referred to as “Finite State Machines”, “Finite State Automata”, or, my personal favorite jargon, “Deterministic Finite State Automata”. This nomenclature is scary to beginners, but it’s not a complex tool.
When we define our states, they could be enumerations, but long-time readers of my blog know that I love to use polymorphism instead of enumerations. They give us the benefit of storing the information that each state needs within the state object itself, which I find particularly elegant. A concrete example: if we needed access to the request (for example to cancel it), we could ask the state for it, and only the Loading state actually needs to store that request. All the other states could respond to that message and return nil.
The above object might be reimplemented like so:
- (instancetype)init {
self = [super init];
if (!self) return nil;
self.state = [InitialState new];
return self;
}
- (void) performAPIRequest {
if (self.state.isLoadingState) {
return;
}
Request *request = [RequestFactory requestWithSuccessBlock:^{
self.state = [CompletedState new];
} failureBlock:((^)(NSError *error)){
self.state = [[FailureState alloc] initWithError:error];
}];
self.state = [[LoadingState alloc] initWithRequest:request];
[request send];
}
- (void)cancel {
self.state = [CancelledState new];
}
- (void)setState:(State *)newState {
[self transitionFromState:self.state toState: newState];
_state = newState;
}
- (void)transitionFromState:(State *)oldState toState:(State *)newState {
if (newState.isCancelledState && oldState.isLoadingState) {
[oldState.request cancel];
} else if (newState.isCompletedState && oldState.isLoadingState) {
//inform delegate of completion
} else {
[[InvalidTransitionException new] raise];
}
}
While this is a lot more code for such a simple thing, notice how much more it does than the first example. We’ve separated the object’s path through the states from what the object actually does when transitioning to those states. We could add multiple Failure states for the different ways we can expect this to fail. This explicitness is valuable, since it forces us to think about how our object transforms over time. Note the exception that’s raised on an invalid transition. If there’s ever a transition that isn’t defined, the app will crash and you can easily determine why.
Since you have to define the states yourself, using a state machine is sometimes easier to hand-roll than to rely on a pre-packaged library. Nevertheless, such libraries exist.
The benefits of using state machines are myriad. First, explicitly storing the states and transitions that are valid in your system leaves fewer nooks and crannies for bugs to hide out in. It is said that bugs are just states that you haven’t defined yet. If your object is defined by four booleans, it can be in 16 different states, all of which require testing. Imagine how many states it can have with integers, or strings! A state machine limits the number of possible configurations your object can be in, and defines them formally.
Having all of the transitions in one place will help you see the user’s flow through the system. What happens if this step takes longer than expected? Clearly-defined transitions make it painfully obvious what happens if an event happens out of order. Since every transition flows through one point, it is trivial to log all of the transitions. You can use that information to determine how your object went off the rails.
Well-named states like these make it easier for new developers to quickly understand your system. Instead of asking “What does self.request mean and why are we checking for its presence?”, your new developer can immediately go to asking higher-level questions. State machines don’t tend to be used until its too late, but good naming is valuable even if you have only two states.
You’ll note that in the only example of architecture that Apple has presented (WWDC 2014 Session 232), they make great use of state machines. You can find the transcipt of that talk here, and the sample code on this page, under “Advanced User Interfaces Using Collection View”.
Heraclitus said that you can never step in the same river twice. State machines take this implication and make it obvious in your objects. Start when your class is young, and take advantage of the explicitness of state machines to help you reason about the complex code in your system. It’s never too early to make the jump from five poorly-managed instance variables to one beautiful state machine.
Pure functions are functions that don’t cause side effects. Their output is deterministic, meaning that given the same input, they will always return the same output. They also don’t access anything global. For example, if a pure function relied on a random number generator, the seed for that generator would have to be passed in as a parameter. With no external forces acting on them, these functions are easy to test and easy to reason about.
As I write more code, I find that the classes that I enjoy writing the most are those that resemble pure functions. I’ve taken to calling these classes “pure objects”.
What is a pure object? A pure object is initialized with several parameters, and responds only to a few readonly messages. Ideally, it doesn’t access any global state, like singletons. If it does, it allows those to be overridden externally.
The interface for a pure object has three components.
The inputs, which are passed to the initializer. These are the analog to the parameters of a pure function.
Read-only access to the inputs. The purpose of this access is two-fold: first, they let you query the object to understand its inputs; second, they create instance variables to store those inputs. Crucially, these references can’t be changed once they are set in the initializer.
The outputs, which are also represented as read-only properties.
Let’s take a look at an example interface:
@interface SKTimeAgoRenderer
- (instancetype)initWithDate:(NSDate *)date locale:(NSLocale *)locale;
@property (nonatomic, readonly) NSDate *date;
@property (nonatomic, readonly) NSLocale *locale;
@property (nonatomic, readonly) NSString *longTimeAgo; //"2 minutes ago"
@property (nonatomic, readonly) NSString *shortTimeAgo; //"2m"
@end
This specific example can be referred to as decoration. A date object is wrapped in a Renderer, which “decorates” it with extra behavior. Presenters and policies, which I’ve also written about on this blog, are other examples of decoration.
Used up and immediately discarded, pure objects are often short-lived:
[[[SKTimeAgoRenderer alloc] initWithDate:aDate locale:[NSLocale currentLocale]] shortTimeAgo];
The discerning reader might ask, why pass the date into the initializer? We could just as easily make a single TimeAgoRenderer and use it on multiple dates via a message like -shortTimeAgoForDate:.
Passing the date to the initializer makes for a much simpler object. With the multiple-use TimeAgoRenderer, internal methods that needed no parameters before (like -dateInTheLastDay, -dateWasYesterday, and -dateInTheLastYear ) would all need the date to be passed to them, a certified code smell.
Further, with the single-use object, self.date never changes, which reduces bugs and increases understandability. The only downside to discarding the object is allocation time, which, at close to 9 nanoseconds, is minimal. Initializing with the date yields simplicity and clarity with little penalty.
In what other ways is our pure object like a pure function? To return more than one result, a pure function takes advantage of a tuple, which is an ordered list of values. Not only can we return multiple values, our outputs are named and can be accessed in any order. (Python uses “named tuples”, but most languages don’t have that feature yet.) Modern functional languages, such as Haskell, take advantage of lazy evaluation. In a similar way, our pure objects can be created in one part of the code, with their outputs uncalculated until they are required.
Pure functions also take advantage of currying. Currying a function lets you pass the initial parameters to a function to create a new function that only needs the final parameters. For example, we can make an addFive by passing only one of the necessary parameters to the add function:
add(5, 3); //8
addFive = add(5); //a curried function that will add 5 to its input
addFive(3); //8
We can do something similar with our pure objects, using convenience initializers. Assuming our normal use will probably pass [NSLocale currentLocale] for the locale, we can create a convenience initializer:
- (instancetype)initWithDate:(NSDate *)date {
return [self initWithDate:date locale:[NSLocale currentLocale]];
}
This is slightly different than currying, since we have to define the curry ahead of time. It also has an advantage over currying, since we can “curry” the parameters in any order. The big benefit of defining convenience initializers is that we can inject our own parameters (such as the locale) when needed, such as during testing.
To make the usage even easier, we can wrap our entire object in a class method, like [SKTimeAgoRenderer shortTimeAgoForDate:date]. We get the best of both worlds: a short incantation for the most common use case, as well as the ability for verbosity when the situation demands it.
Of course, side-effects are the whole reason we write code; we can’t only write these types of objects. Some of our objects must communicate with the network, write things to databases on disk, and render to the display buffer. Using small objects like these is a great technique to increase expressiveness, concentrating our side-effect-ful code and keeping our responsibilities separate.
Since the rise in popularity of emoji in the United States, people of color have been asking why there are no emoji that look like them. Adding an extra emoji for each icon in each race seems extreme, so those more cynical of us just assumed it was another byproduct of this society and this industry, never to be fixed. But there’s a new draft specification for representing racial diversity in emoji. Prayer hands emojis abound.
There are currently four skin colors depicted in the Apple emoji set. The first type are the unrealistic skin tones, like yellow, orange, and purple. The second type are the emoji with decidedly white skin tones, like the boy and girl emoji and the various body parts. The third and fourth skin tones are found on one emoji each: MAN WITH TURBAN (U+1F473) and MAN WITH GUA PI MAO (U+1F472).
Even the yellow-tinted emoji represent whiteness in our culture. You don’t need to look further than the Simpsons to see what I mean. If you’re not white, it’s hard to feel like these emoji were made for you, unless you’re a brown man wearing a turban and or a man wearing a gau pi mao.
How Unicode works
The Unicode standard (specifically UTF-8, the most common encoding scheme) is a clever solution to a complex problem. You can (and should!) learn more about Unicode in Tom Scott and Brady Haran’s Computerphile video as well as Joel Spolsky and Tim Bray’s articles on Unicode. UTF-8 is characterized by backwards compatibility with ASCII, variable-width encoding, character composition, and variation selectors.
Emoji is a catchall term for a several different “blocks” of graphical glyphs described in the Unicode standard. Originally from a Private Use Area used by the Japanese cariers SoftBank Mobile and DoCoMo, they were moved to a public block as of version 6.0 of the Unicode standard. Unicode 7.0 added a new set of emoji, and this specification has been presented for incorporation into version 8.0.
When a glyph rendering engine begins laying out characters, it sometimes renders two characters as one glyph. This is called a ligature, and explains why NSLayoutManager has methods like -glyphRangeForCharacterRange:actualCharacterRange: to convert between character ranges and glyph ranges. I hope you didn’t think I was going to let you get away without some code in this post!
This techinque of merging two characters at rendering time is how this new emoji spec handles various skin tones. An emoji followed by a skin color swatch can be merged at glyph-rendering time to represent that emoji with that skin color.
If the emoji rendering system doesn’t implement this ligature, it will display the emoji followed by a graphical representation of the swatch of the skin color. This fallback is ugly, to be sure, but it signals the intent of emoji-sender effectively.
The first thought any person of color will have about this scheme is that it relegates non-white skin colors to mere “alternates” to the norm. Fortunately, the authors considered this as well:
When a human emoji is not followed by a emoji modifier character, it should use a non-realistic skin tone, such as that typically used for the smiley faces, or a silhouette.
In all likelihood, most implementations will use Simpsons-yellow for the “non-realistic skin tone”, but imagine a world where the default emoji skin color were blue or purple! That’s beautiful to me.
What this means
The minimum viable product reigns in our industry. An MVP can only bear affordances for a subset of its audience, who are, among other qualities, white, male, cisgendered, visibly straight, and often American. When a minimal product is designed with only the majority in mind, the product can only be successful for those users.
The lack of racially diverse emoji are only one symptom of this problem. As Austin Seraphim told us at CocoaLove, the blind have learned to expect very little from tech companies. HP developed a face tracking camera that literally renders black people invisible. Facebook’s privacy settings outed closeted gay people without permission, wrenching families apart. Quora won’t let people with non-American names use their website. In all of these cases, thoughtlessness prevailed and people were left out.
So when people ask me why diversity is important, they need only look around. Because without diverse teams building the technology that we all rely on, we’ll continue to make these mistakes again: we’ll leave people behind. Diverse teams build products with affordances that help us all feel included.
The Unicode consortium was forward-thinking enough to make the Unicode standard flexible enough to enable this change, and that’s a testament to its creators. I celebrate this change and look forward to many more like it.
The authors of this spec suggested the Fitzpatrick Scale for skin tones. I’m a 4.
What’s in a name? Isn’t this stuff supposed to be a hard problem anyway? What is a DownloadController, and how is it different from a DownloadQueue ?
I love this quote by Graham Lee so much:
Anything that isn’t evidently data or evidently graphics gets put into the amorphous “controller” collection, which eventually sucks your entire codebase into its innards like a black hole collapsing under its own weight.
Charged with bridging between models and views, view controllers grow to become untenable nightmares quickly. It’s become valuable to question what the word “controller” even means to us.
What’s a gesture recognizer? It gets attached to views, suggesting that maybe it belongs in the view layer, but it’s definitely not a view. However, in Smalltalk (the first object-oriented lanugage), user input is classically a controller concern. Which of the two is it? The answer is simple. A gesture recognizer is just that: a gesture recognizer.
Not all objects have to be models, views, and controllers. Some objects are data sources, gateways, routers, and interactions; others still are players, presenters, and operations.
Models and views are easy; they are Things. Representing them in your brain in not a challenge. Controllers are much more amorphous. With models and views, shared behavior in them can be moved up to a superclass, and specific behavior can be moved down to a subclass. All of the models in your app could descend from one class; say, MTLModel. Views could do the same (and in fact, must, if you expect them to play nicely with UIKit). View controllers also have lots of shared behavior and benefit from a supertype. What would a hypothetically-named SKController superclass even do? With responsibilities so broad, what would that interface declaration even be? It would probably be empty.
@interface SKController : NSObject
@end
What useful thing is this object doing? What shared behavior can we give it? And if there’s nothing sensible in SKController, why call things controllers at all? They’re also all objects. It would be just as appropriate to append the word “Object” to every class name.
The harm caused by the “Controller” suffix is subtle, too. When you call something a Controller, it absolves you of the need to separate your concerns. Nothing is out of scope, since its purpose is to control things. Your code quickly devolves into a procedure, reaching deep into other objects to query their state and manipulate them from afar. Boundless, it begins absorbing responsibilities.
The scope of a policy object is very narrow, and it quickly becomes obvious when it starts acting outside of that scope. It has very clearly defined boundaries, and it’s perfectly testable. It is everything a MusicLibraryController is not.
A MusicLibraryController can be decomposed into a MusicLibrary with LibraryItems, a Player, and a PlayQueue. We’ve granted a specific role to each component. A new developer needs to know only the names of classes to intuit how they work together. She can do this without reading a single line of code. That’s incredibly powerful.
Naming is hard, but calling things “controller” is easy. (“Manager” is a cop-out too. Sorry.) Spend a little time and think about what role your new object plays in your architecture. Give it an expressive name based on its purpose. If a meaningful name is hard to pin down, it might encapsulate more than one responsibility. Break it up. Read Gang of Four and Patterns of Enterprise Application Architecture from cover to cover. Learn about the different patterns that programmers have been using for decades. Or make up your own! If it feels right, try it out. You’ll know if it’s good.
