When working with Swift on the server, most of the routing frameworks work by associating a route with a given closure. When we wrote Beacon, we chose the Vapor framework, which works like this. You can see this in action in the test example on their home page:

import Vapor

let droplet = try Droplet()

droplet.get("hello") { req in
    return "Hello, world."
}

try droplet.run()

Once you run this code, visiting localhost:8080/hello will display the text “Hello, world.”.

Sometimes, you also want to return a special HTTP code to signal to consumers of the API that a special action happened. Take this example endpoint:

droplet.post("devices", handler: { request in
	let apnsToken: String = try request.niceJSON.fetch("apnsToken")
	let user = try request.session.ensureUser()
    
	var device = try Device(apnsToken: apnsToken, userID: user.id.unwrap())
	try device.save()
	return try device.makeJSON()
})

(I would like to detail what goes into niceJSON in a future blog post, but for now, ignore it.)

This is a perfectly fine request and is similar to code from the Beacon app. There is one problem: Vapor will assume a status code of 200 when you return objects like a string (in the first example in this blog post) or JSON (in the second example). However, this is a POST request and a new Device resource is being created, so it should return the HTTP status code “201 Created”. To do this, you have to create a full response object, like so:

let response = Response(status: .created)
response.json = try device.makeJSON()
return response

which is a bit annoying to have to do for every creation request.

Lastly, endpoints will often have side effects. Especially with apps written in Rails, managing and testing these is really hard, and much ink has been spilled in the Rails community about it. If signing up needs to send out a registration email, how do you stub that while still testing the rest of the logic? It’s hard thing to do, and if everything is in one big function, it’s even harder. In Beacon’s case, we don’t have don’t have many emails to send, but we do have a lot of push notifications. Managing those side effects is important.

Generally speaking, this style of routing, where you use a closure for each route, has been used in frameworks like Flask, Sinatra, and Express. It makes for a pretty great demo, but a project in practice often has complicated endpoints, and putting everything in one big function doesn’t scale.

Going even further, the Rails style of having a giant controller which serves as a namespace for vaguely related methods for each endpoint is borderline offensive. I think we can do better than both of these. (If you want to dig into Ruby server architecture, I’ve taken a few ideas from the Trailblazer project.)

Basically, I want a better abstraction for responding to incoming requests. To this end, I’ve started using an object that I call a Command to encapsulate the work that an endpoint needs to do.

The Command pattern starts with a protocol:

public protocol Command {

	init(request: Request, droplet: Droplet) throws
    
	var status: Status { get }

	func execute() throws -> JSON
	
}

extension Command: ResponseRepresentable {
    
	public func makeResponse() throws -> Response {
		let response = Response(status: self.status)
		response.json = try execute()
		return response
	}
    
}

We’ll add more stuff to it as we go, but this is the basic shell of the Command protocol. You can see see just from the basics of the protocol how this pattern is meant to be used. Let’s rewrite the “register device” endpoint with this pattern.

droplet.post("devices", handler: { request in
	return RegisterDeviceCommand(request: request, droplet: droplet)
})

Because the command is ResponseRepresentable, Vapor accepts it as a valid result from the handler block for the route. It will automatically call makeResponse() on the Command and return that Response to the consumer of the API.

public final class RegisterDeviceCommand: Command {

	let apnsToken: String
	let user: User

	public init(request: Request, droplet: Droplet) throws {
		self.apnsToken = try request.niceJSON.fetch("apnsToken")
		self.user = try request.session.ensureUser()
	}

	public let status = Status.created

	public func execute() throws -> JSON {
		var device = try Device(apnsToken: apnsToken, userID: user.id.unwrap())
		try device.save()
		return try device.makeJSON()
	}
}

There are a few advantages conferred by this pattern already.

  1. Maybe the major appeal of using a language like Swift for the server is to take advantage of things like optionals (and more pertinently, their absence) to be able to define the absolute requirements for a request to successfully complete. Because apnsToken and user are non-optional, this file will not compile if the init function ends without setting all of those values.
  2. The status code is applied in a nice declarative way.
  3. Initialization is separate from execution. You can write a test that checks to that the initialization of the object (e.g., the extraction of the properties from the request) that is completely separate from the test that checks that the actual save() works correctly.
  4. As a side benefit, using this pattern makes it easy to put each Command into its own file.

There are two more important components to add to a Command like this. First, validation. We’ll add func validate() throws to the Command protocol and give it a default implementation that does nothing. It’ll also be added to the makeResponse() function, before execute():

public func makeResponse() throws -> Response {
	let response = Response(status: self.status)
	try validate()
	response.json = try execute()
	return response
}

A typical validate() function might look like this (this comes from Beacon’s AttendEventCommand):

public func validate() throws {
	if attendees.contains(where: { $0.userID == user.id }) {
		throw ValidationError(message: "You can't join an event you've already joined.")
	}
	if attendees.count >= event.attendanceLimit {
		throw ValidationError(message: "This event is at capacity.")
	}
	if user.id == event.organizer.id {
		throw ValidationError(message: "You can't join an event you're organizing.")
	}
}

Easy to read, keeps all validations localized, and very testable as well. While you can construct your Request and Droplet objects and pass them to the prescribed initializer for the Command, you’re not obligated to. Because each Command is your own object, you can write an initializer that accepts fully fledged User, Event, etc objects and you don’t have to muck about with manually constructing Request objects for testing unless you’re specifically testing the initialization of the Command.

The last component that a Command needs is the ability to execute side effects. Side effects are simple:

public protocol SideEffect {
	func perform() throws
}

I added a property to the Command protocol that lists the SideEffect-conforming objects to perform once the command’s execution is done.

var sideEffects: [SideEffect] { get }

And finally, the side effects have to be added to the makeResponse() function:

public func makeResponse() throws -> Response {
	let response = Response(status: self.status)
	try validate()
	response.json = try execute()
	try sideEffects.forEach({ try $0.perform() })
	return response
}

(In a future version of this code, side effects may end up being performed asynchronously, i.e., not blocking the response being sent back to the user, but currently they’re just performed synchronously.) The primary reason to decouple side effects from the rest of the Command is to enable testing. You can create the Command and execute() it, without having to stub out the side effects, because they will never get fired.

The Command pattern is a simple abstraction, but it enables testing and correctness, and frankly, it’s pleasant to use. You can find the complete protocol in this gist. I don’t knock Vapor for not including an abstraction like this: Vapor, like the other Swift on the server frameworks, is designed to be simple and and that simplicity allows you to bring abstractions to your own taste.

There are a few more blog posts coming on server-side Swift, as well as a few more in the Coordinator series. Beacon and WWDC have kept me busy, but rest assured! More posts are coming.

Ashley Nelson-Hornstein and I built an app for hanging at WWDC. It took 5 weeks to build. It’s called Beacon, and you can get it on the App Store today.

Beacon is a way to signal to your friends that you’re down to hang out. You can set up an event, and your friends will be able to see those events, and let you know that they want to come. Beacon answers questions like “Who’s free?” “Who likes persian food?”, “We have 2 spots for dinner, and who would want to come?” without the messiness of having to text your entire address book. Each event has a big chat room for organizing, and honestly, goofing around in those chat rooms has been some of the most fun of the beta. Beacon is, at its heart, a very social app.

Ashley and I did a ton of work in these few weeks, trying to get this app from concept to production. I never built an app this fast before, and it’s been an exhilarating ride. In addition to being a stellar dev, Ashley’s got a great eye for the holes in the product and the user loop, which let us tighten up the experience before putting the app in the hands of all of our friends. This project absolutely wouldn’t have worked without her.

Linda Dong also contributed a considerable amount of design work, giving the app life and personality. Before her touch, the “design” was the output of two developers, and you can imagine what a horror show that was.

From a technical perspective, one of the things I’m most excited about is the server side of this project. Chris and I got to talk about this on the last episode of Fatal Error season 2 (Patreon link). Beacon finally gave me the chance to build an application for the server using Swift. We chose Vapor for the framework, purely for the quality of support (mostly a friendly Slack channel) and the size of the community using it.

Swift on the server is a budding project. Builds are slow, test targets are hard to set up, there’s no Xcode (which means no autocompletion or command/option-clicking), Foundation isn’t complete, there’s almost no library support, documentation is god-awful, and everything is changing extremely quickly. Nevertheless, it’s fun as hell to write Swift for the server, and I don’t regret the decision. I think it’s most comparable to writing Swift 1 or 1.1 in a production iOS app. Potentially a problematic decision, but the language was so fun that everyone who did it had no complaints. I think in 2 or 3 years, Swift on the server will be where Swift in the client is now, and that will be a great time indeed.

I’ve written web apps in Node, Rails, and various PHP frameworks, and while it’s possible to take advantage of their dynamically typed features for certain patterns, I often felt like I was programming without a safety net. I felt forced to write tests to make sure that various code paths were getting hit and the right methods were being called.

With Swift on the server, you get all the Swift niceties you’re used to: enums, generics, protocols, sequences, and everything else. All of the other tiny pieces of knowledge of Swift that you’ve built up over the last weeks and months are valid and useful.

A few scattered thoughts on Swift on the server:

  • Because you have a type system, building up little abstractions is much easier, and you can change those abstractions without worrying that protocol conformances down the line will be broken. Optionals are excellent. It’s so nice to know that you have something. For example, in the Event model, I have a non-optional User called organizer, and I have total confidence that through any code path in the app, if I have an event, I will have an organizer.
  • I definitely want Linux support for Sourcery. There’s a lot of boilerplate in model code on the server (sometimes even more than the client) and Sourcery would help with that pain a lot.
  • Because everything in Vapor is synchronous, I rewrote my networking library to simply return a value (or throw) for each request. This makes writing network code so simple, and I find it quite a shame that we can’t take advantage of this on the client as well. I hold out hope that Swift’s async/await implementation will be the answer to some of these woes.

We don’t know if Beacon is a viable product for the broader market, but we think it’ll be a lot of fun at WWDC and we look forward to organizing lots of ad hoc events with all of you awesome people. Find me on the app, and let’s hang out.

This is a post in a series on Advanced Coordinators. If you haven’t read the original post or the longer follow-up, make sure to check those out first. The series will cover a few advanced coordinator techniques, gotchas, FAQs, and other trivia.

When working with coordinators, all flow events should travel through the coordinator. Any time a view controller intends to change flow state, it informs the coordinator, and the coordinator can handle side effects and make decisions about how to proceed.

There is one glaring exception to this rule: when a navigation controller navigates “back”. That back button is not a traditional button, so you can’t add handlers to it to send messages up to the coordinator. Further, its associated behavior is performed directly by the navigation controller itself. If you need to do any work in a coordinator when a view controller is dismissed, you need some way to hook into that behavior.

While there are other less common examples, the primary use case is when you have a sub-flow that takes place entirely within the context of another navigation controller. Coordinators typically own one navigation controller exclusively, but sometimes, a subset of the flow with in a navigation controller stack needs to be broken out into its own coordinator, usually for reuse purposes. That separate coordinator shares the navigation controller with its parent coordinator. If the user enters the child coordinator (entering the sub-flow) and then taps the back button, that child coordinator needs to be cleaned up. If it’s not cleaned up, that coordinator’s memory will effectively be leaked. Further, if they enter that flow a second time, we might have two of the same coordinator, potentially reacting to similar events and executing code twice.

So, we need a way to know that the navigation’s back button has been tapped. The UINavigationControllerDelegate is the easiest way to get access to this event. (You could subclass or swizzle, but let’s not.)

There are a few ways to use this delegate to solve this problem, and I’d like to highlight two of them. The first is Bryan Irace’s approach to tackling this problem. He makes a special view controller called NavigationController that allows you to push coordinators in addition to pushing view controllers.

I’ll elide some of the details and give an overview of the approach, but if you want a full details, I recommend reading his whole post. The main thing to note in his code is:

final class NavigationController: UIViewController {

	// ...

	private let navigationController: UINavigationController = //..
	
	private var viewControllersToChildCoordinators: [UIViewController: Coordinator] = [:]
  
	// ...

}

This shows the way that this class works. When you add a new coordinator to this class, it creates an entry in this dictionary. The entry maps the root view controller of a coordinator to the coordinator itself. Once you have that, you can conform to the UINavigationControllerDelegate.

extension NavigationController: UINavigationControllerDelegate {    
	func navigationController(navigationController: UINavigationController,
		didShowViewController viewController: UIViewController, animated: Bool) {
		// ...
	}
}

At that point, if the popped view controller is found in the coordinator dictionary, it will remove it, allowing it to correctly deallocate.

There’s a lot to like about this approach. Coordinator deallocation is handled automatically for you, when you this class instead of a UINavigationController. However, it comes with a few downsides, as well. My primary concern is that the NavigationController class, which is a view controller, knows about and has to deal with coordinators. This is tantamount to a view having a reference to a view controller.

I think there are some goopy bits on the inside of UIKit where views know about their view controllers. I haven’t seen the source code, but the stack trace for -viewDidLayoutSubviews suggests that there’s some voodoo going on here. Sometimes, components in a library may be coupled together more tightly, in order to make the end user’s code cleaner. This is the tradeoff that Bryan is making here.

If you don’t want to make that tradeoff, you can bring the navigation controller delegate methods to the parent coordinator, where they can live with all the other flow events. This is my preference. By making the coordinator into the delegate of the navigation controller, you can maintain the structure of the coordinator: namely that it is the parent of the navigation controller. When you get the delegate messages that a view controller was popped off, you can manually clean up any coordinators that need to be dealt with.

extension Coordinator: UINavigationControllerDelegate {    
	func navigationController(navigationController: UINavigationController,
		didShowViewController viewController: UIViewController, animated: Bool) {
		
		// ensure the view controller is popping
		guard
		  let fromViewController = navigationController.transitionCoordinator?.viewController(forKey: .from),
		  !navigationController.viewControllers.contains(fromViewController) else {
			return
    	}
		
		// and it's the right type
		if coordinator is FirstViewControllerInCoordinator) {
			//deallocate the relevant coordinator
		}
	}
}

This approach is slightly more manual, with the up- and downsides that come with that: more control and more boilerplate. If you don’t like the direct type check, you can replace it with a protocol.

You’ll also need to re-enable the interactivePopGestureRecognizer by conforming to UIGestureRecognizerDelegate and returning true for the shouldRecognizeSimultaneouslyWithGestureRecognizer delegate method.

Both approaches are good ways of handling decommisioned coordinators and ensuring that they correctly deallocate, and these techniques are crucial for breaking out your subflows out into their own coordinators so they can be reused.

This is a post in a series on Advanced Coordinators. If you haven’t read the original post or the longer follow-up, make sure to check those out first. The series will cover a few advanced coordinator techniques, gotchas, FAQs, and other trivia.

When splitting up the responsibilities of a view controller, I do a curious thing. While I leave reading data (for example, a GET request, or reading from a database or cache) in the view controller, I move writing data (such as POST requests, or writing to a database) up to the coordinator. In this post, I’ll explore why I separate these two tasks.

Coordinators are primarily in charge of one thing: flow. Why sully a beautiful single responsibility object with a second responsibility?

I make this distinction because I think flow is the wrong way to think about this object’s responsibility. The correct responsibility is “handle the user’s action”. The reason to draw this distinction is so that the knowledge of when to “do a thing” (mutate the model) and when to “initiate a flow step” can be removed from the view controller. I don’t want a view controller to know what happens when it passes the user’s action up to a coordinator.

You can imagine a change to your app’s requirements that would make this distinction clear. For example, let’s say you have an app with an authentication flow. The old way the app worked was that the user typed their username and password into one screen, and then the signup request could be fired. Now, the product team wants the user to be able to fill out the profile on the next screen, before firing off the signup request. If you keep model mutation in the view controller and the flow code in the coordinator, you’ll have to make a change to both the view controller and the coordinator to make this work.

It gets even worse if you’re A/B testing this change, or slowly rolling it out. The view controller would need an additional component to tell it how to behave (not just how to present its data), which means either a delegate method back up to the coordinator or another object entirely, which would help it decide if it should call inform the coordinator to present the next screen or if it should just post the signup call itself.

If you keep model mutation and flow actions together, the view controller doesn’t have to change at all. The view controller gets to mostly act like it’s in the view layer, and the coordinator, with its fullness of knowledge, gets to make the decision about how to proceed.

Another example: imagine your app has a modal form for posting a message. If the “Close” button is tapped, it should dismiss the modal and delete the draft from the database (which, let’s say, is saved for crash protection). If your designer decides that they want an alert view that asks “Are you sure?” before deleting the draft, your flow and your database mutation are again intertwined. Showing the dialog is presenting a view controller, which is a flow change, and deleting an item from the database is a model mutation. Keeping these responsibilities in the same place will ease your pain when you have to make changes to your app.

One additional, slightly related note: the coordinator’s mutative effect on the model should happen via a collaborator. In other words, your coordinator shouldn’t touch URLSession directly, nor any database handle, like an NSManagedObjectContext. If you like thinking about view models, you might consider a separation between read-only view models (which you could call a Presenter) and write-only view models (which you could call an Interactor or a Gateway). Read-only view models can go down into the view controller, and write-only view models stay at the coordinator level.

The line between model mutation and flow step is thinner than you’d expect. By treating those two responsibilities as one (responding to user action), you can make your app easier to change.

This the going to be the first post in a series on Advanced Coordinators. If you haven’t read the original post or the longer follow-up, make sure to check those out first. The series will cover a few advanced coordinator techniques, gotchas, FAQs, and other trivia. Let’s dig in.

I’m often asked how to migrate an app from using storyboards or per-view controller code-based flow to an app using coordinators. When done right, this refactoring can be done piecemeal. You will continuously be able to deploy your app, even if the refactoring isn’t complete.

To acheive this, the best thing to do is start from the root, which for coordinators is called the “app coordinator”. The app delegate holds on to the app coordinator, which is the coordinator that sets up all the view controllers for your app’s launch.

To understand why we start from the root of the app, consider the opposite. If we started from some leaf flow (like, say, a CheckoutCoordinator), then something needs to maintain a strong reference to the coordinator so that it doesn’t deallocate. If the coordinator deallocates, none of its code can run. So, deep in an app, if we create a coordinator, something will have to hold on to it.

There are two ways to prevent this deallocation. The first option is to make a static reference. Because there will likely only ever be one CheckoutCoordinator, it’ll be easy to stuff it in to a global variable. While this works, this isn’t an ideal choice, since globals hinder testability and flexibility. The second option is to have the presenting view controller maintain a reference to the coordinator. This will force a little complexity onto the presenting view controller, but will allow us to remove more complexity from all the view controllers that are managed by that coordinator. However, this relationship is fundamentally flawed. View controllers are usually “children” to coordinators, and when programming, children shouldn’t know who their parents are. I would liken this to a UIView having a reference to a UIViewController: it shouldn’t happen.

If you have a situation where you’ve decided that you absolutely must start with some child flow in your app, then you can make it work with one of the two methods above. However, if you have the power to start from the root, that’s my recommendation.

One other benefit to starting from the root is that the authentication flow is often close to the root of the app. Authentication is a great flow to isolate away into its own object, and a nice testbed for proving coordinators in your app.

Once you’ve moved the root view controller of the app to your AppCoordinator, you can commit/pull request/code review/etc the code. Because every other view controller transition continues to work, the app will still be fully functional in this halfway state. At this point, working one-by-one, you can start to move more view controller transitions over to the coordinator. After each “flow step” is moved to your coordinator, you can commit or make a pull request, since the app will continue to work. Like the best refactorings, each of these steps are mostly just moving code around, sometimes creating new coordinators as needed.

Once all of your transitions have been moved over to coordinators, you can do further refactorings, like separating iPhone and iPad coordinators into individual objects (instead of one coordinator that switches on some state), making child flows reusable, and better dependency injection, all of which are enabled by your new architecture.

Swift is commonly described as a “safe” language. Indeed, the About page of swift.org says:

Swift is a general-purpose programming language built using a modern approach to safety, performance, and software design patterns.

and

  • Safe. The most obvious way to write code should also behave in a safe manner. Undefined behavior is the enemy of safety, and developer mistakes should be caught before software is in production. Opting for safety sometimes means Swift will feel strict, but we believe that clarity saves time in the long run.

  • Fast. Swift is intended as a replacement for C-based languages (C, C++, and Objective-C). As such, Swift must be comparable to those languages in performance for most tasks. Performance must also be predictable and consistent, not just fast in short bursts that require clean-up later. There are lots of languages with novel features — being fast is rare.

  • Expressive. Swift benefits from decades of advancement in computer science to offer syntax that is a joy to use, with modern features developers expect. But Swift is never done. We will monitor language advancements and embrace what works, continually evolving to make Swift even better.

For example, when working with things like the Optional type, its clear how Swift increases safety. Before, you would never know which variables could be null and which couldn’t. With this new nullability information, you’re forced to handle the null case explicitly. When working with these “nullable” types, you can opt to crash, usually using an operator that involves an exclamation point (!). What is meant by safety here is apparent. It’s a seatbelt that you can choose to unbuckle, at your own risk.

However, in other cases, the safety seems to be lacking. Let’s take a look at an example. If we have a dictionary, grabbing the value for some given key returns an optional:

let person: [String: String] = //...
type(of: person["name"]) // => Optional<String>

But if we do the same with an array, we don’t get an optional:

let users: [User] = //...
type(of: users[0]) // => User

Why not? The array could be empty. If the users array were empty, the program would have no real option but to crash. That hardly seems safe. I want my money back!

Well, okay. Swift has an open development process. Perhaps we can suggest a change to the swift evolution mailing list, and—

Nope, that won’t work either. The “commonly rejected” proposals page in the swift-evolution GitHub repo says that they won’t accept such a change:

  • Make Array<T> subscript access return T? or T! instead of T: The current array behavior is intentional, as it accurately reflects the fact that out-of-bounds array access is a logic error. Changing the current behavior would slow Array accesses to an unacceptable degree. This topic has come up multiple times before but is very unlikely to be accepted.

What gives? The stated reason is that speed is too important in this particular case. But referring back to the About page linked above, “safe” is listed as a description of the language before “fast”. Shouldn’t safety be more important than speed?

There is a fundamental contention here, and the solution lies in the definitions of the word “safe”. While the common understanding of “safe” is more or less “doesn’t crash”, the Swift core members usually use the same word to mean “will never access incorrect memory unintentionally”.

In this way, Swift’s Array subscript is “safe”. It’ll never return data in memory beyond the bounds allocated for the array itself. It will crash before giving you a handle on memory that doesn’t contain what it should. In the same way that the Optional type prevents whole classes of bugs (null dereferencing) from existing, this behavior prevents a different class of bugs (buffer overflows) from existing.

You can hear Chris Lattner make this distinction at 24:39 in his interview with ATP:

We said the only way that this can make sense in terms of the cost of the disruption to the community is if we make it a safe programming language: not “safe” as in “you can have no bugs,” but “safe” in terms of memory safety while also providing high performance and moving the programming model forward.

Perhaps “memory-safe” is a better term than just “safe”. The idea is that, while some application programmers might prefer getting back an optional instead of trapping on out-of-bounds-array access, everyone can agree that they’d prefer to crash their program rather than let it continue with a variable that contains invalid data, a variable that could potentially be exploited in a buffer overflow attack.

While this second tradeoff (crashing instead of allowing buffer overflows) may seem obvious, some languages don’t give you this guarantee. In C, accessing an array out-of-bounds gives you undefined behavior, meaning that anything could happen, depending on the implementation of the compiler that you were using. Especially in cases when the programmer can quickly tell that they made a mistake, such as with out-of-bounds array access, the Swift team has shown that they feel like this is an acceptable place to (consistently!) crash, instead of returning an optional, and definitely instead of returning junk memory.

Using this definition of “safe” also clarifies what the “unsafe” APIs are designed for. Because they muck about in memory directly, the programmer herself has to take special care to ensure that she’ll never allow access to invalid memory. This is extremely hard, and even experts get it wrong. For an interesting read on this topic, check out Matt Gallagher’s post on bridging C to Swift in a safe fashion.

Swift and the core team’s definition of “safe” may not line up 100% with yours, but they do prevent classes of bugs so that programmers like you don’t have to think about them day-to-day. It can often help to replace their usage of “safe” with “memory safe” to help understand what they mean.

One often-misused piece of the Swift standard library is Sequence’s enumerated() function. This function give you a new sequence with each element in the original sequence and a number that corresponds to that element.

enumerated() is misunderstood. Because it provides a number with each element, it can be an easy solution for a number of problems. However, most of those problems are solved better with other techniques. Let’s go over some of those cases, highlight why they’re flawed, and go over better abstractions for solving them.

The primary issue with using enumerated() is that people think it returns each index and its element, but that’s not quite what’s going on. Because it’s available on every Sequence, and sequences aren’t even guaranteed to have indexes, we know they’re not indexes. Within the code, the variable is called offset, not index, which is a naming convention I will stick to in this article. The offset is always an integer, starting from 0, increasing by one for each element. For Array, this happens to correspond to the index, but for basically every other type, it doesn’t. Let’s take a look at an example.

let array = ["a", "b", "c", "d", "e"]
let arraySlice = array[2..<5]
arraySlice[2] // => "c"
arraySlice.enumerated().first // => (0, "c")
arraySlice[0] // fatalError

Our variable arraySlice here is, unsurprisingly, an ArraySlice. However, its startIndex is notably 2, not 0. But when we call enumerated() and first on it, it returns a tuple with an offset of 0 and its first element, “c”.

Put another way, you think you’re getting

zip(array.indices, array)

but you’re actually getting

zip((0..<array.count), array)

and this will result in wrong behavior anytime you’re working with anything other than an Array.

Besides the fact fact you’re getting an offset, not an index, there are other issues with using enumerated() as well. Many of the times you might think to use enumerated(), there are better abstractions to take advantage of. Let’s take a look at a few.

The most common use I see of of enumerated() is using the offset from one enumerated array to grab a corresponding element from of another array.

for (offset, model) in models.enumerated() {
	let viewController = viewControllers[offset]
	viewController.model = model
}

While this code works, it relies on both models and viewControllers being arrays, indexed by integers, starting from 0. It also relies on each array having the same length. If the models array is shorter than the viewControllers array, nothing bad will happen, but if the viewControllers array is shorter than the models array, we’ll have a crash. We also have this extra variable offset that isn’t doing very much. A nicer, Swiftier way to write this same code is:

for (model, viewController) in zip(models, viewControllers) {
	viewController.model = model
}

This code is much more focused and now works with any Sequence types. It will also handle mismatched array lengths safely. Way better.

Let’s look at another example. This code adds an autolayout constraint between the first imageView and its container, and then also between each pair of image views.

for (offset, imageView) in imageViews.enumerated() {
	if offset == 0 {
		imageView.leadingAnchor.constraint(equalTo: containerView.leadingAnchor).isActive = true
	} else {
		let imageToAnchor = imageView[offset - 1]
		imageView.leadingAnchor.constraint(equalTo: imageToAnchor.trailingAnchor).isActive = true
	}
}

This code sample has similar problems. We want pairs of elements, but using enumerated() to get numbers that we can manipulate means we’re mucking about with indexes manually when we can we working at a higher level. zip can help us here as well.

First, let’s write some code to deal with the container constraint on the first element:

imageViews.first?.leadingAnchor.constraint(equalTo: containerView.leadingAnchor).isActive = true

Next, lets handle the pairs:

for (left, right) in zip(imageViews, imageViews.dropFirst()) {
	left.trailingAnchor.constraint(equalTo: right.leadingAnchor).isActive = true
}

Done. No indexes, works with any (multi-pass) Sequence, and more focused.

(You can also box up the pairing code into an extension and call .eachPair() if you like.)

There are some valid uses of enumerated(). Because what you’re getting is not an index, but just an integer, the right time to use it is when you need to work with a number (not an index) that corresponds to each element. For example, if you need to position a bunch of views vertically, where each one has y coordinate that corresponds to some height multiplied by the offset in the sequence, enumerated() is appropriate. Here’s a concrete example:

for (offset, view) in views.enumerated() {
	view.frame.origin.y = offset * view.frame.height
}

Because the offset here is being used for its properties as a number, enumerated() works great.

The rule of thumb here is simple: if you’re using enumerated() for an index, there might be a better way to solve your problem. If you’re using it for its properties as a number, thumbs up emoji.

When writing code, the biggest enemy is complexity. Maintaining levels of abstraction and allowing the developers who work in our codebases to fluidly move up and down through those concepts is crucial to large software projects.

Comments are a tool that have a veneer of managing complexity, but subtly hurt the codebase instead of helping.

My perspective on comments comes from two facts: 1) Comments don’t compile. 2) Comments are usually a subdued color in your syntax highlighter. Because they don’t compile and because they fade away from sight, it’s very easy to ignore them as you make changes to the code. If you make changes and don’t update the comments, you end up with a comment that doesn’t accurately reflect the content of code.

In an ideal world, you’d be able to catch this in code review, but I’ve never seen that work in practice. Code review tools have syntax highlighting as well, causing comments to fade into the background in that context as well. Also, because code review diffs only show a few lines around the change, out-of-date comments can only be found if the comment is close to the change itself. If you change a line deep in a method that changes what the preconditions of the method are, your reviewers won’t see the comment and won’t be able to tell you to update it.

There are a few tips and tricks to avoid the most common comments, some of which are covered in a blog post by an old manager of mine, and others of which Andrew can’t even dream of because he writes code in Ruby, a dynamically typed language.

  1. Name things well! The first step to avoiding comments is to avoid things like single-letter names, abstract names, and vague names. The more precise you can be with the name, the less you’ll need a comment.

  2. If a method has preconditions, add an assertion that will crash the app (at least in debug, if not always!) if an invalid value is passed in. If you only accept positive, non-zero integers, write a bit of code that says so: precondition(int > 0).

  3. Even better than run-time assertions is compile-time ones. If your method accepts only non-empty arrays, you could write precondition(!array.isEmpty). But you could also use a type that can never express an empty array. Users of your API will now never be able to pass an empty array into that parameter.

    In the same vein, do you have a bool parameter that’s better expressed via an enum with two named cases? Are your optionals better expressed as other enums? Reveal your intentions in your naming.

  4. Mark hacks, temporary code, and prototype code liberally. I often use a prefix like hack_ to mark that a function is not written ideally. An underscore in a method name in Swift looks so out of place that I directly feel the pain of making my codebase worse, and I’m inspired to try and fix it. We recently made a function prefixed with shouldReallyBeInTheCoordinator_ because something needed to get through code review, but the code wasn’t in the right class. The needs of your codebase and your own sensibilities become aligned when bad code is made to be ugly code as well. Other good prefixes: perf_ and temp_.

  5. Via Mark Sands: you can encode the IDs from your bug tracker into method names and they’ll show up in stack traces. UIKit references radar numbers in a few cases. This is real:

     -[UIViewController _hackFor11408026_beginAppearanceTransition:animated:]
    
  6. Don’t be afraid to describe the “why” of a function in its name. You’re allowed to make methods called updateFrameOnNextTickBecauseAutoLayoutHasntCompletedYet(frame: CGRect). The compiler doesn’t care how long your methods are named, and code is read much more than its written. Comments are just words, and so are method names. Future maintainers of that codebase will appreciate your verbosity.

  7. Make helper functions, like a function called TODO(date: Date, message: String) that logs an error (or even better, crashes in debug) if the TODO isn’t fixed by some date. Another example via Jordan Rose.

  8. Encode any algorithmic requirements into tests. If all of the above fails, and you can’t rely on the preconditions, types, and method names to solve a particular problem, write a test for it. This is especially good for edge cases. If someone rewrites that code, the tests will break, and they’ll know they have to handle that case with their new code.

Remember: this isn’t an excuse to write impenetrable code and not comment it! The code must be clear if you’re going to skip commenting it. Comments for me are a last resort. If I can find of any other way to express my intentions to the next programmer, I don’t add a comment.

Further Reading

Sometimes you need to modify your view controller to do a new thing. One thing leads to another, and you find yourself adding an optional variable property to the view controller, which will be set in some cases and not in others.

I think that more often than not, this is a flawed approach. There are a few reasons for this. First, a class with a optional property that is only used sometimes has a weak sense of identity. Put another way, adding optional properties blurs the fundamental meaning of the type. Second, this optional property doesn’t carry any semantic meaning. What does it mean about the state of this object if the type is nil? A casual reader of your code can’t tell in what cases the property will be nil, or what ramifications it has for the object. Third, code will continue to mutate. One optional property becomes two optional properties, which becomes three, and before you know it, you’ll end up at the bottom of a slippery slope. If we want to express that this value must exist if that value is nil, we can’t do that with simple optionals.

In all the codebases I’ve seen, I’ve found two primary reasons why you might need an optional property on your view controller. I’ll explore them both and suggest better patterns to solve each problem.

The first reason that you might have a problematic optional property is when you won’t necessarily have that object or piece of data every time this view controller is used.

One example of this that came up recently was a view controller that was being presented from a push notification in some cases. It needed to show a specific message that came from that notification. The simplest solution to this problem was to add an optional string property:

class LocationViewController: UIViewController {

	//...
	
	var notificationMessage: String?
	
	//...
}

Other code in the view controller switched on the message’s existence to determine which views to allocate, how to lay them out, and so on. The optionality of the property represents more than existence of a simple string. It had implications in the rest of the view controller and the rest of the view layer.

The more essential point here is that the string now no longer represents a string that might be there or might not — it now represents the presentation style or mode that the view controller is in. Was it created in the context of a push notification or through normal browsing? The answer is in this barely related property!

To fix this problem, we have to make this mode fully explicit. Once it’s a first class citizen in this view controller, its effect on the view controller will be much more obvious.

class LocationViewController: UIViewController {

	//...
	
	enum Mode {
		case fromNotification(message: String)
		case normal
	}
	
	var mode: Mode
	
	//...
}

As Sandi Metz says, there’s never one specialization. With an optional property, a sometimes-I-do-it-this-way, the code doesn’t admit that the nil case of this property carries meaning as well and is really its own specialization. With an enum, this is reified and formalized in code.

Note that our new enum has a very similar shape to the enum that defines the Optional type.

enum Optional<Wrapped> {
	case some(Wrapped)
	case none
}

It has a few extremely useful differences, though.

First, semantics. some and none are abstract; normal and fromNotification have meaning associated with them. Readers of your code will thank you.

Second, extensibility. If another mode is added to this view controller, we have a better means of fully describing it. If the new mode can never overlap with these two modes, we can add another enum case, with whatever necessary associated data. If that new mode can overlap with both of these current modes, it can be a new enum and a new property altogether. The state of the object is more readily describable. Either of these choices are better than adding yet another optional property for the new mode.

Third, extensibility again. Because LaunchViewController.Mode is a first-class type, we can add functions and computed properties to it. For example, the height of the label that holds the notification message is probably dependent on the presence of the message itself. Therefore, we can move that code to the enum itself:

extension Mode {
	var notificationLabelHeight: CGFloat {
		switch self {
		case .normal: return 0
		case .fromNotification(let message): return message.size().height
		}
	}
}

Moving this data to a richer type gives you gains on all of these fronts, with very little code investment.

The second reason you might use an optional property is a subset of the first. In some cases, it’s not that the optional property represents a different mode of the view controller, it’s that it represents a temporal dimension to your code. You can’t initialize the property with a value because you don’t have it yet. Common examples of this are when you’re fetching something from the network, or waiting on some system resource that takes too long to retrieve and needs to be asynchronous.

class UserViewController: UIViewController {
	
	//...
	
	// will be loaded asynchronously
	var user: User?
	
	//...
	
}

This kind of problem can sometimes be papered over if the data comes back in array form. Since you can represent the non-existent state with the empty array, this problem may still be lurking, even if you’re not using an optional. The number of times that I’ve had a tough time adding empty states to a table view controller is a testament to this extent of this problem.

Since this problem is a subset of the first problem, we can solve it in the same way, with an enum:

enum LoadingState<Wrapped> {
	case initial
	case loading
	case loaded(Wrapped)
	case error(Error)
}

While this solution works, there is a better abstraction for managing asynchronous state. A value that doesn’t exist yet but will at some point in the future is best represented by a Promise. Promises have several advantages, depending on your use case.

First, promises allow mutation, but only once and only from the pending state. Once a promise has been mutated (“fulfilled”), it can’t change again. (If you need something that can be updated multiple times, a Signal or Observable is what you’re looking for.) This means that you can have semantics that are similar to let, but still manage asynchronous data.

Next, promises have facility for adding blocks that will get fired when a value comes in. If the property remained a simple optional property, these added blocks are equivalent to code in a didSet property observer. However, promise blocks are more powerful, since more than one can be added, and they can be added on the fly from any place in the class. Further, if they’re added when the promise is already fulfilled with a value, they’ll immediately execute.

Lastly, if needed, promises handle errors as well. For certain kinds of asynchronous data, this is crucial, and you’ll get it for free.

If you’re using my Promise library, you can create a pending Promise with the empty initializer, and fulfill it at any time with the fulfill method.

When it comes to optional properties, sometimes they reveal things about your code that may not have been apparent before. When you see yourself adding an optional parameter to a view controller, ask yourself, what does this optional really mean? Is there a better way to represent this data?

I often get a better picture of a type’s purpose from knowing what its instance variables are. Once you know the underlying structure of that type, it’s more obvious how to use it. The converse is also true: it can sometimes be hard to figure out what exactly an object is for, without seeing the layout of its members. This is especially apparent with Apple’s closed-source classes.

A great example of this is NSDate. When I started programming, I had a tough time figuring out how to use the NSDate and all of its corresponding sibling objects, like NSDateComponents, NSDateFormatter NSCalendar. Why do you have to use NSCalendar to add 2 days to date? The boundaries between these classes seem arbitrarily drawn, and that makes it hard to know where to look to find any specific functionality you’re looking for.

The key revelation for me was understanding what NSDate really was under the hood, which made all the rest of the pieces fall together. NSDate is just a fancy wrapper around a double. That’s it. And a close reading of the docs reveals this fact:

NSDate objects encapsulate a single point in time, independent of any particular calendrical system or time zone.

All NSDate does is store a double representing the number of seconds since 00:00:00 UTC on January 1, 2001. This number of seconds has nothing to do with timezones, days of the week, months, daylight savings time, leap seconds, or leap years. If the calculation can be done with just the number of seconds since that reference date, it goes on NSDate. Otherwise, it goes somewhere else.

Examples of things that can be done with just this double are comparison (earlierDate, laterDate), equality, and time interval calculations (which also returns a number of seconds). distantFuture and distantPast are obvious now too, they’re just the largest expressible doubles, in positive and negative forms.

For other stuff, you have to go to other classes and objects. For example, adding one day to a moment in time, while it can done by just adding 24*60*60 seconds to an NSDate, is best handled via NSCalendar, to avoid running afoul of issues with Daylight Savings Time, leap seconds/days, and other non-standard issues that can crop up with time. This blog post lays out the case for using NSCalendar for these calculations.

Because NSDate doesn’t store any information about the expected month of a particular date, if you want to change that month, you have to use an object that knows about and can split apart the various “components” that make up a date. For this, we use a NSDateComponents object. I find that thinking about how I might write a similar class can help me understand what it’s for and how its layout works. Take a look at the public interface for NSDateComponents and see if you can figure out how its data might be stored internally.

I found another interesting example of using an object’s property storage layout to learn things about the nature of that object when I was working on my Promise library. If you look at the properties that each of my Promise objects stores, you’ll see three things:

public final class Promise<Value> {
    
    private var state: State<Value>
    private let lockQueue = DispatchQueue(label: "promise_lock_queue", qos: .userInitiated)
    private var callbacks: [Callback<Value>] = []

Each promise has its current state (such as .pending, fulfilled, or .rejected), a queue to ensure thread-safety, and an array of callbacks to call when the promise is either fulfilled or rejected.

After writing my library, I looked at some Signal/Observable implementations to see if I could understand them. I found JensRavens/Interstellar to be the most straightforward. I look at the instance properties of each of its Signal objects, and I found a very similar structure:

public final class Signal<T> {
    
    private var value: Result<T>?
    private var callbacks: [Result<T> -> Void] = []
    private let mutex = Mutex()

Something to store the current state, something to store the callbacks, and something to store the thread-safety primitive. The order is different, and they used a mutex instead of a queue, but it’s otherwise identical. The only difference between these two types is a semantic one: promises can clear their callbacks when they’re completed (releasing them and the variables they capture), and signals must keep their callbacks around.

I think this principle can also help in the design of your own types too. Take a look at the properties on an object that you’re working on. Does each property have a purpose? Does it contribute to the overall identity of the object? Are there properties that are used in some instances of that type, but not others? If so, those properties might belong somewhere else. Making sure that the instance variables available on a type are tightly controlled and used fully ensures that our object has a well-defined purpose in your application.