This mindset is as much a part of our culture and identity as it is good practice for our craft. Sometimes I wonder if developers come to somewhat view themselves as robots, running some internal software whose rules can be optimised and fine-tuned. With this mindset we strive for the human element of our practice to have the same traits as our software; it should be rule-based, consistent, and reproducible.

We love making the non-conforming conform, and there’s no more fertile ground than that of a code review. Here’s the thing though, what if conformity isn’t always worth the effort that we put in to it? What if we’re wasting our time on things that don’t make a difference to anything?

Every team has their ‘things’ that they’ve become perhaps a bit too obsessive over. Whitespace, braces, indentation, comment lengths, ternary statements vs if-else. Things that they might have once picked up on as being an indicator of code quality, but which they may be in danger of believing are the indicator of code quality.

A short story

I once worked with a developer who was really strict on identifying places in the code where we were using redundant self (using self.something when the self could be inferred), and each pull request was met with a flurry of suggestions to remove the redundant selfs. Seems reasonable, right? I thought that this was making things consistent, so I also took part in the war on redundant self.

Then that guy left the team, and we became a little less strict about it, and you know what happened?

Nothing.

Nothing caught fire. Nothing broke. Sure, there were a few more redundant selfs, and the team preference was loosely still to omit them, but they were harmless. There was one positive effect though: less noise in the code reviews, and more focus on the things that matter.

Things that actually matter

Some things in your code review really matter. For instance, a team member might spot a bug, suggest and architectural improvement, or identify some way to remove complexity.

The problem is that code review comments are often flooded with things like “Why not make this guard statement a single line”, or “We leave two whitespaces after a protocol declaration” or “You could use a ternary statement instead of an if-else” or “private comes before static in the method declaration”.

All of these things have the same thing in common. Once you make the change, the code does exactly 100% the same thing as it did before. It’s no more maintainable, no more scalable. You could recompile this, diff the binary, and see that it’s the same as before. So why do we bother?

You’re not a robot

Everyone’s at least once in their life lined up all the drinks cans in their fridge so that the labels all face the right way. I know you’ve done it. I also guess that you decided not to carry on this practice on account of it having no real value.

But there is some value. It’s aesthetically pleasing, and gives you a moment of satisfaction when you open the fridge. Perhaps it even allows you to identify the correct drink some small percentage faster. Now, if I were building a robot to fill the fridge then I’d probably make it line the drinks up all the same way, because why not?

If I, a human with limited time and energy, am filling the fridge, however, then I’ll skip the bit where I spin all the drinks around to face the same way, because the benefit is infinitesimally small compared to the time and effort that I expend in doing so.

We should see our code reviews like this. We have to weigh up if our energy is being well spent in fixing these ‘nitpicks’. If something really is just a nitpick, then well, probably not!

But it annoys me!

Sometimes it’s worth fixing something just so you can put your mind at ease and that nitpicky thing you care about will stop irking you. That’s ok, and is one of the best arguments for using tools such as linters; once all of the braces and spaces are uniform then you can just concentrate on the important things, right?

But we should recognise that it’s our own flaw to be irresistibly drawn to the insignificant minutiae of code formatting, rather than focussing on the details that contribute to the success of the code. Requesting a change to the code that results in exactly the same logic is the lowest value suggestion we could make. If the compiler doesn’t care, you have to question how much should you?

We have to be careful that we don’t come to believe that consistency of the minute details is what makes code good. What makes code good is scaleable architecture, useful abstractions, good design. No one really comes to regret writing a guard statement on a single line. At least, I’ve never heard that as being grounds for a rewrite, or sinking a once prosperous team.

Formatting churn

The behaviour that we’re encouraging is the search for an ever increasing number of things to be pedantic about. We just add more and more things to the list. It starts with braces, then spaces, then naming conventions, then class layout, etc. Eventually you will probably yearn for the time that you could just get on with your job.

The worst type of suggestion is one from a reviewer who doesn’t actually know their own rules. They might like this guard statement on a single line, but that other one across multiple, but they can’t quite articulate why. In this case, the team can never learn or align on these rules, and this just results in ‘formatting churn’ for each pull request, that creates a drag on the team’s output.

New developers learn this ‘habit’ from their more experienced peers. Rather than considering the different trade offs between design patterns and approaches, they come to view surface level consistency and ‘neatness’ as being the goal that all teams should aspire too.

Once we come to believe that this is what makes code good, then we start actively search for new things to be pedantic about. More conditions to check in code review, more reasons to request changes to a pull request, believing that each of these rules represents some kind of mark of quality in our codebase.

In reality though, it doesn’t matter, and the team who just live in blissful ignorance of these ‘inconsistencies’ will probably put more energy into the things that do matter, such as what their code actually does.

A thought experiment

Imagine that you could wear a pair of glasses that would allow you to see other people’s code with consistent formatting that aligned with all the nitpicky rules and conditions that you like, would you wear them?

I think it’s a no brainier. You would be able to focus just on what the code did, without being irked by the fact that the author used an if-else when you just ‘know’ that a ternary statement would look better here.

We can have these magic glasses! They’re just a mindset. We just need to be more chill about stuff. Here’s how we review an if-else condition:

We see that it’s an if-else, read what’s in the if condition, read what’s in the else condition, check the logic is sound, and just move on.

So, what’s the takeaway?

I’m not advocating for us not caring about things, but we should care about things proportional to the value that they provide. Shuffling some whitespace around is simply not worth the feedback cycle that you put in to it. It’s not worth the time it takes to make the comment. It’s not worth the time it takes for the author to fix it. It’s not worth clogging up the CI for a new build. You could have spent that time doing something of actual value.

Rather than nitpicking, we should instead focus on what the code actually does, not how well it aligns with a set of arbitrary habits that we’ve come to have Stockholm syndrome for.

So my advice is: when you’re about to make a nitpicky suggestion, take a deep breath, and just… let it go.

I’ve come to a realisation though. There’s no such thing as clean code.

‘Clean’ isn’t a measure of anything useful. Code can’t be clean simply because ‘clean’ doesn’t describe anything about code.

Clean code is good code, right?

When people describe code as clean they usually mean that the code is good in some way.

The thing is, code can be good for a variety of reasons. It could be:

• Readable
• Understandable
• Simple
• Performant
• Safe
• Elegant
• Testable
• Encapsulated
• Scaleable
• Maintainable
• Reusable
• Easy to delete
• Neat and tidy
• Noninvasive
• Systematic
• Consistent
• or any number of other things

But these traits are in some ways at odds with each other. The most simple code is probably not the most testable. All those interfaces and injected dependencies make for convenient testing, but have a cost in terms of simplicity.

Your heavy reliance on singletons may make things easy to understand, but it might not lead to a maintainable application.

It could be argued that some of these things are fundamentally opposing forces that can’t all be satisfied simultaneously. Engineering is about trade-offs, so we’ve got be aware of the trade-offs we’re proposing, and be able to discuss them as a team.

If the code is good, we’ve gotta say why

When someone says a solution is ‘clean’, they’re often touting it as the superior option without being able to rationalise why.

If we want to have constructive discussion around technical solutions then we’ve got to be able to articulate to each other why one solution is better than another. It’s no good arguing over which solution is the ‘cleanest’, as if we should get our clean-o-meter out any weigh up each solution according to this mysterious metric.

It’s actually quite difficult to express sometimes why one approach is better or worse than another, but it’s a skill that is worth honing.

Would you rather have discussion like this?

“I like solution X, it feels much cleaner.”

Or this?

“I like solution X. It decouples the error message presentation from the core logic. It’s easier to understand, because you don’t have to consider both at the same time. This separation also unlocks some testability, as we can mock either object whilst testing the other. It does come at the expense of requiring the parent object to inject the dependencies, but that’s a worthwhile tradeoff for the testability.”

The second statement actually conveys something tangible about the pros and cons of the solution we’re discussing. Terms like ‘clean’ allow us to cop-out, rather than working to improve our ability to articulate our ideas.

We need to use precise terms

Coding is generally a team sport. If you’re hacking away on your own then you can do what you want, but when we’re working with a team then we’ve got to discuss our ideas. Being able to have discussion about technical solutions using language that is specific and has common understanding throughout the team is invaluable in understanding one another.

‘Clean code’ means a different thing to everyone.

To some developers, code is clean because it has a well defined architecture. To other developers, code is clean simply because it uses a consistent formatting style.

Words like ‘encapsulated’, ‘testable’, ‘mockable’, ‘reusable’ have meanings that we can all agree on. When we use more specific words that describe the various code traits that affect our project then we can be sure that we’re all on the same page.

‘Clean’ has the same level of precision as ‘good’. You can say that code is good, just as you can say that it’s clean, but that doesn’t absolve you from having to justify that with more concrete rationale.

So what is clean code?

I’ve come to the conclusion that often when we describe code as ‘clean’ when we think it’s good but we’re not entirely sure why. It just feels like the right solution.

Or sometimes we do know why the code is good, but we can’t find the words to articulate it, and somehow the conclusion of our blog post just reads “See! Look how much cleaner that it is!”.

It’s good to build that intuition, but we can’t just stop there. We need to dig deeper beyond those feelings to understand and articulate why we think the code is good. What characteristics does this code have that other solutions don’t? Are those the characteristics that make the most sense for our project? Perhaps it’s actually not the right solution after all.

Hopefully I can convince you that you don’t really need clean code, you need _____ code. It’s up to you to fill in that blank with words that describe what your project requires.

At my last job I worked on a fairly large iOS and tvOS app for nearly 4 years, during which time we transitioned almost the whole app to Swift. At least the first year was spent learning how not to do a language transition, during the second and third we figured things out and really hit our stride, and by the fourth we had something resembling a formalised approach.

I’ve realised that there’s a bunch of teams out there still maintaining Objective-C projects, and struggling to make much headway on a Swift transition. So in this post I’m going to tell you what I learned along the way.

How not to do it

The naive approach is to simply decide to write all new code in Swift. Surely, then, over time there will be more Swift code and less Objective-C.

This is probably most teams’ initial idea, and it was ours too. I can tell you that it didn’t move the needle very much.

It was difficult to gracefully integrate new Swift code into existing Objective-C classes and systems. A year down the line we still had a mostly Objective-C code base. Almost anything of any real importance was still in Objective-C, and all we’d really built was some surface level Swift on top of an Objective-C core.

Swift and Objective-C are not friends

Swift and Objective-C are interoperable, right?

Swift and Objective-C are interoperable in the same way that you can plug a VHS player into your 4K TV. It’s possible, but if that’s your plan then you really don’t need a 4K TV anyway.

Everything that’s great about Swift has to be sacrificed for Objective-C interoperability. Value types, generics, enums with associated values, optionals.

If you have a whole bunch of Objective-C and you write a tiny bit of Swift in the middle, then that Swift ends up being crappy Swift. Instead of using value types for your model objects, you end up with model classes that inherit from NSObject, all your enums use Int as a raw value, and everything is optional. (Urgh!)

We’ll call this code ‘Objective-C compromised Swift’.

It feels good that you’re writing Swift, but remember our goal is to go from A to B, where A is a fully Objective-C codebase, and B is a fully Swift one.

Once we remove all of our Objective-C code we’ll be at the end goal, right?

Nope, we’ll be at some awkward point between A and B. Yes, theoretically the project will be in Swift, but once the Objective-C is removed none of the compromises will make sense anymore. All of our model objects will be classes for no reason, and we’ll have to do a second refactoring pass to get to our fully Swift vision.

It took us a while to realise that this is what we were creating. We would end up sort of ‘halfway’ to the goal of having a Swift codebase. The Swift code would be horrible to work with, and the team would be suggesting yet another refactoring effort to rewrite things in a nicer way (management absolutely wouldn’t approve of this!).

The goal is that the Swift that we write needs to idiomatic Swift, following patterns that make sense in Swift. But how to we do that, if our new Swift lives alongside our existing Objective-C?

Swift islands

The key is to not tightly intermingle the two languages. What we need is separation between them. If system X is written in Objective-C and system Y is written in Swift, then only the api for system Y needs to be compatible with Objective-C. The innards of that system can use all the Swift goodness that we’re after.

This is great in theory, but we also don’t want to completely rewrite whole subsystems of our application in Swift in one go. We want a gradual approach that moves us to closer to having a full Swift codebase over time.

The approach that we developed was what we called ‘Swift islands’.

Our codebase would end up with three types of code.

• Idiomatic Swift that we intend to keep.
• Temporary Swift to Objective-C shims.
• Legacy Objective-C.

An island looks like this:

We can start anywhere that makes sense. The key is that we start with a small Swift ‘island’. It can be just be one Swift class. We write nice Swifty code that we can be proud of, and then we provide shims that our Objective-C code uses to interface with it.

When we come to write some new Swift code that lives in the same area, we interface with the Swift apis directly, not via the shims. Every time we rewrite some adjacent code in Swift, the island will expand a bit. This new code will provide more shims, but as we rewrite, the island expands and we can start removing the shims from inside of the island once there are no longer any Objective-C calls to them.

There’s no need to limit ourselves to a single island, either. As we start writing Swift in new areas of the app we create new little islands of Swift, and these will grow and merge together.

The feeling of deleting a shim is great. You’re left with idiomatic Swift that the team can be proud of and that you can maintain into the future.

How to Shim

Let’s look at some shimming strategies. There’s a variety of ways to write a shim, but these are the ones that I’ve got the most mileage from.

The important thing to remember is that shims are temporary. This means they can be a bit ugly. Remember, the thing that we’re optimising for is what the code will be like once the shim is removed, not the experience of using the shim.

The shim extension

The simplest way to add a shim is to write a extension on your class that provides an Objective-C compatible api.

@objc class NotificationScheduler: NSObject {
  enum NotificationTime {
    case now
    case scheduled(date: Date)
  }

  func sendNotification(time: NotificationTime, text: String) {
    ...
  }
}

/// Objective-C Shim
extension NotificationScheduler {
  @objc objc_sendNotificationNow(text: String) {
    sendNotification(.now, text: text)
  }
  
  @objc objc_sendNotificationAtDate(date: Date, text: String) {
    sendNotification(.scheduled(date: date), text: text)
  }
}

NotificationScheduler has the Swift api that we want, but the enum with associated values for NotificationTime prevents it from being callable from Objective-C. Instead, we provided an additional api for Objective-C using a shim extension.

The caveat with this approach is that we still had to make the class visible to Objective-C, so it required the @objc attribute and needed to inherit from NSObject. A small concession, but preferable to a fully Objective-C compatible api.

Also I like to prefix the shim methods with objc_. This makes the shims stand out, and prevents anyone accidentally calling them from Swift code. Remember, we’ll delete them, so it’s ok for them to be ugly.

The value type wrapper

Value types are pretty easy to deal with, we simply wrap them up, like this:

struct User {
  var name: String
  var email: String
}

@objc class User_ObjC: NSObject {
  let user: User
  init(user: User) {
    self.user = user
  }
  
  @objc var name: String {
    user.name
  }
  
  @objc var email: String {
    user.email
  }
}

We use User inside of our Swift island, and we wrap it in User_ObjC when it travels outside of the island through a shim, and unwrap User_ObjC to get back a User if it travels into our Swift island.

We can provide shims that facilitate all of this for us:

@objc class UserManager: NSObject {
  func getCurrentUser() -> User { ... }
  func updateUser(user: User) { ... }
}

extension UserManager {
  @objc func objc_getCurrentUser() {
    User_ObjC(user: getCurrentUser())
  } 
  @objc func objc_updateUser(user: User_ObjC) {
    updateUser(user: user.user)
  }
}

Awkward conversions (and how to cheat them)

Some Swift concepts are harder to convert to Objective-C than others. Take this model for a train status:

enum TrainStatus {
  case onTime
  case delayed(minutes: Int)
  case cancelled
}

We might have a table view in Objective-C that lists incoming trains and highlights them red if they’re either cancelled or more than 15 minutes late.

If you have many places where you use this type from Objective-C then you might write a fancy shim.

Or you can cheat:

@objc TrainStatus_ObjC: NSObject {
  var status: TrainStatus
  init(status: TrainStatus) {
    self.status = status
  }
  
  @objc isCancelledOrMoreThan15MinutesLate: Bool {
    switch status {
      case .onTime: return false
      case .delayed(let mins): return mins > 15
      case .cancelled: return true    
    }
  }
}

You might balk at this. This isn’t very good design. We added a computed variable on this object that’s weirdly specific for this one use case, but remember, it’s for a shim! Shims are temporary, and we want them to be quick and easy to produce, and to leave no lasting negative effects on our application design once removed.

I’ve created a bunch of shims just like this and I have no regrets because I’ve since deleted them.

How much investment you make in the shim should be guided by how long you think it will last, and how many use cases you have for it. A long lasting shim should probably provide a reasonable api. A shim that only supports one call site can be pretty naive.

Messaging space

One thing that became evident to me over time was that when you have a collection of objects that work together, where most are Swift but some are Objective-C, you get a sort of ‘lowest common denominator’ effect, where even just a few Objective-C types pollute the design of the whole system. The reason is that these objects want to pass and receive Objective-C friendly types, and force everything around them into an Objective-C friendly style to work with them.

I’m going to call this part of the code the ‘messaging space’.

We can sort of visualise the objects in our application as little self contained boxes. We can then imagine connections between them, and imagine them sending little messages to each other. The space that the boxes sit in is the messaging space.

The messaging space also has a sort of language to it. A predominantly Objective-C messaging space might probably has messages flowing through it containing NSValues and NSNumbers, and model classes inheriting from NSObject.

Being a Swift class in this world is tough. Nothing feels like it really fits nicely with the design of Swift. For a new Swift object to participate here it also needs to pass and receive Objective-C objects.

What we need to do is change the language of the messaging space to be Swift friendly, but without rewriting all of our Objective-C objects. We can do this by creating a Swift wrapper around our Objective-C classes and presenting a Swift friendly api.

Once these shims are in place our new Swift object is much happier, and probably contains much better Swift code.

For example, if we have a food order service declared in Objective-C, the api might import to Swift like this:

class FoodOrderService: NSObject {
  func order(food: Food, completion: (Receipt?, Error?) -> Void)
}

This wouldn’t be an unusual api in Objective-C, but this probably isn’t the design that we’d choose for Swift. The optional Receipt? and Error? completion isn’t very idiomatic, and we’d rather user a Result type.

Let’s wrap our FoodOrderService in a Swift wrapper, providing a nice Swift api. Here’s how I would go about it:

• Rename our existing Objective-C FoodOrderService to FoodOrderService_ObjC.
• Create a new Swift FoodOrderService.
• FoodOrderService will internally hold an instance of FoodOrderService_ObjC, passing on any calls to the legacy service.
• FoodOrderService translate any calls into a Swift friendly API, and can provide translations for model objects such as Food and Receipt too, into value types.

Here’s how it might look:

class FoodOrderService: NSObject {
  private let wrappedService = FoodOrderService_ObjC()
  
  func order(food: Food, completion: (Result<Receipt, Error>) -> Void) {
    wrappedService.order(food: Food_ObjC(food)) { receipt: Receipt_ObjC, error in
      if let error = error {
        completion(.failure(error))
      } else if let receipt = receipt {
        completion(.success(receipt.wrappedReciept))
      } else {
        completion(.failure(“Unexpected: Receipt and error are both nil”))
      }
    }
  }
}

With just a little bit of translation we’re able to provide a sensible Swift api.

• Our completion handler uses Result<Receipt, Error> rather than (Receipt?, Error?).
• We handled the weird case where both Receipt? and Error? are nil in the wrapper, so our call sites don’t have to deal with it.
• We replaced the original Food model with a struct and made a simple refactoring to the old system to reference Food_ObjC instead, and handle conversions in the wrapper.
• We did the same for Receipt, unwrapping the value as it comes out of the old system.

And if we need to still need to provide an Objective-C compatible interface for now, then we can write shims for this wrapper as we did for our ‘real’ Swift types.

It may seem like overkill to have an Objective-C shim for a Swift wrapper around an Objective-C type, but remember this is all a means to an end. If we’re making good progress on our language transition then we’re deleting shims as fast as we’re creating them.

Once the ‘messaging space’ for a cluster of objects is Swift friendly, then all of the interaction between them will be using ‘Swift’ apis. If some of the objects are just wrapped Objective-C types, the rest of the system is oblivious to this, and it will feel like a Swift codebase. You can choose any convenient time in the future to refactor the Objective-C insides of these objects, but these no pressure to do it any time soon.

Good Luck!

Ok, so here’s my list of approaches:

• Create ‘Swift islands’ and expand them over time.
• Create shims for existing Objective-C objects to call your new Swift ones.
• Use value types within the Swift portions of your codebase, and wrap them in Objective-C compatible reference types for the Objective-C parts.
• Try to convert the ‘messaging space’ of each subsystem to Swift as early as possible, and then the messaging space between subsystems.
• Wrap Objective-C types that you’re not ready to tackle yet with Swift friendly interfaces. If these are working well for you, then they can stay as Objective-C on the inside for years.

Moving a codebase of any reasonable size from Objective-C to Swift is a harder challenge than it appears on the surface.

You still need to be prepared that it does require some level of dedicated effort. It’s possible to use the shimming approach for new code that gets written during the course for feature development and make some really good headway. At the end of the day though, no one’s going to rewrite the app delegate in Swift though unless it’s given some dedicated time.

With the shimming approach we were able to move our application from around 15% Swift to around 80% over a couple of years. Some of that required some dictated effort, but much was delivered during the course of feature development. All of the message passing between objects had transitioned to Swift, and the remaining 20% Objective-C was code that has living behind a shim that was working well.

The best part is that the Swift code that we’re left with no longer carries around the baggage of Objective-C interoperability. It’s pure, uncompromising Swift code, designed with a Swift mindset, which is the sort of codebase we all want to work in.

If you do some research on how to do this, you’ll likely come across the following strategy:

• Create a protocol that mirrors the api of the system type that you need to call
• Conform the system type to this protocol. It already has the required api, so there should be no additional code required.
• Inject the dependancy as the protocol
• In production inject the system type, and in your tests inject a mock that adopts the protocol

This works, and I’ve successfully used this strategy myself. I think there’s some issues with this approach though, and for many cases there may be a better alternative. Let’s take a deeper look at the issues that you might be introducing using this technique, and then I’ll propose a possible better solution.

The shadowing technique

I’m going to refer to the technique described above as the ‘shadowing’ technique. Essentially, we have a concrete type that we don’t own, and we want to have an abstraction over it. We create a protocol with the same api as the concrete type, and refer that instead. Here’s an example with FileManager:

protocol FileManagerProtocol: class {
  func fileExists(atPath path: String, isDirectory: UnsafeMutablePointer<ObjCBool>?) -> Bool
}

extension FileManager: FileManagerProtocol {}

The type we’re testing will only know about FileManagerProtocol, so in production we’ll inject the real FileManager, and in our tests we’ll inject a MockFileManager:

class MockFileManager: FileManagerProtocol {
  var fileExists = true
  var isDirectory = false
  func fileExists(atPath path: String, isDirectory: UnsafeMutablePointer<ObjCBool>?) -> Bool {
    isDirectory?.pointee = self.isDirectory
    return fileExists
  }
}

Of course, our test can alter the fileExists and isDirectory properties of the MockFileManager in order to assert that a specific behaviour occurs when a file exists or not. Lets look at a few downsides with this approach though.

No deprecation warnings

Both Objective-C and Swift support annotations to mark types or methods as deprecated. When we call a deprecated method in our code, we will trigger a compiler warning, letting us know that we need to update to a newer version of the api.

These annotations only exist on the concrete type though. If we refer to the type through a protocol, even with the same api, then the compiler won’t warn us at all. This can allow usage of deprecated apis to go unnoticed.

The api might not be great anyway

Let’s take a look at that method signature again:

func fileExists(atPath path: String, isDirectory: UnsafeMutablePointer<ObjCBool>?) -> Bool

Personally, I’m not a fan. There’s clearly a bit of Objective-C era baggage here. No one really wants to deal with UnsafeMutablePointer<ObjCBool>? if they can avoid it, right?

It would be nicer if the api looked more like this:

func fileExists(atPath path: String) -> Bool
func directoryExists(atPath path: String) -> Bool

Given that we think this api is awkward to work with, why do we want to proliferate it around our codebase?

It’s not really abstraction

By mirroring the api of a type, we’re creating a code level abstraction over it, because we can refer to it via the interface instead of the concrete type.

What we’re missing, though, is the opportunity to create a semantic abstraction. Imagine a new and improved api becomes available for working with the file system. It’s unlikely that it’s going to have this exact method:

func fileExists(atPath path: String, isDirectory: UnsafeMutablePointer<ObjCBool>?) -> Bool

We’d have to change the FileReader protocol anyway, which means that we’ll have to alter every call-site, which means our abstraction didn’t buy us much.

There’s also something that doesn’t sit right with me about letting a third party api dictate the api for my abstraction. I want to own my abstractions! If I need to work with a type that reads files, I’d prefer to decide on what public api that would have, and then lean on a third party type inside of the implementation, rather than have the api of the third party type dictate to my application what the interface to read files should be.

There are limits here, of course. If the api that you wish to have and the api that the third party type has don’t map easily on to each other, then you may need an additional layer of abstraction between them that you can test.

The wrapping technique

Let’s look at another approach, where we’ll wrap the type that we want to abstract away from rather than ‘shadow’ its api.

That would look more like this:

protocol FileReader {
  func fileExists(atPath path: String) -> Bool
  func directoryExists(atPath path: String) -> Bool
}

class FileReaderImpl: FileReader {
  func fileExists(atPath path: String) -> Bool {
    var isDirectory: ObjCBool = false
    let exists = FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory)
    return exists && !isDirectory
  }

  func directoryExists(atPath path: String) -> Bool {
    var isDirectory: ObjCBool = false
    let exists = FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory)
    return exists && isDirectory
  }
}

So now we can do this:

let fileReader: FileReader = FileReaderImpl()
let fileExists = fileReader.fileExists(atPath: "path/to/file")

You might shudder a bit at the FileReaderImpl name - I did the first time I used this approach. We shouldn’t really worry about it though, because we should only initialise the type once, and inject it in to an object that depends on it. Any other references to this type should be through the FileReader protocol.

Let’s see what we’ve earned ourselves:

Easy Mocking

Mocking just became a lot easier, because we’re using an api that is more to our taste than the original.

class MockFileReader: FileReader {

  var findsFile = true
  var findsDirectory = true

  func fileExists(atPath path: String) -> Bool {
    return findsFile
  }

  func directoryExists(atPath path: String) -> Bool {
    return findsDirectory
  }
}

// We can just inject the mock in to the type that we want to test
let mock = MockFileReader()
mock.findsFile = false

let objectToTest = MyObject(fileReader: mock)

Deprecation warnings are back!

We only ever call the FileManager type directly inside of FileReaderImpl. Because we’re not re-declaring its api in a protocol, if any of its methods become deprecated then we’ll get deprecation warnings!

We have a semantic abstraction

If a newer and better thing comes out than FileManager, then we can swap for a different implementation, whilst still keeping the same api that we designed. In fact, our code is actually completely abstracted from the FileManager type, it only knows about FileReaders. We can change the innards of FileReaderImpl to utilise a different underlying type and our code would happily work with it.

Ok, so what’s the catch?

Ok, technically, if you want to nit-pick, we lost a tiny bit of testability. Because we wrapped the FileManager in a FileReader protocol, we’re unable to test the inside of FileManagerImpl to ensure that it actually interacted with FileManager in the correct way.

Personally, I don’t think this is too much of a loss. The implementation inside of the wrapper should be so simple that a bug is unlikely and would be squashed early. You can think of it as a very basic translation layer from the protocol api (FileReader) to the concrete type’s api (FileManager). In some cases you may even be just forwarding a call with the same method signature.

The benefits outweigh the costs in my opinion, and let’s be honest - your code base probably isn’t so tested that you’ll lose sleep about that little binding function inside of a wrapper!

Let’s consider a social networking feed, comprised of text posts, image posts, and article posts. We want only our image posts to have a UIImage associated with them, and only our article posts to have a URL associated with them.

We could model this with an enum:

enum Post {
    case text(String)
    case image(String, UIImage)
    case article(String, URL)
}

The enum feels like a reasonably good fit here because it enforces exhaustiveness. The compiler will force us to consider all of the cases of the enum, and let us know if we missed one.

Associated values also help us tie additional information to each case, and only that case. You have to switch on the enum to extract the associated information, and you only get an image with the image case, and an article with the article case.

We could simply pass that information to a set of table view cells (one for each post type) to create a feed:

func cellForRow(at indexPath: IndexPath) -> UITableViewCell {
    let post = posts[indexPath.row]
    switch post {
        case let .post(text):
            let cell = tableView.dequeueCell(“TextCell”)
            cell.configure(text)
            return cell
        case let .image(text, image):
            let cell = tableView.dequeueCell(“ImageCell”)
            cell.configure(text, image)
            return cell
        case let .article(url):
            let cell = tableView.dequeueCell(“ArticleCell”)
            cell.configure(text, url)
            return cell
    }
}

There’s a few problems with this design though. The first is that is doesn’t scale. You can look forward to this future:

case post(text, url, headline: String, subtitle: String, sharedVia: User?, originalComment: String?, promoted: Bool)

Another issue with relying heavily on enums with associated values is that they’re a pretty unstructured way to organise information. What if you have a view of your timeline that just shows all of the media, without text? You’ll soon end up in underscore hell with this type of thing:

switch Post {
   case .post(_, let image, _, _, _, _):
       //... Show the image cell
}

Just think, every time you added one of those new values you would have to go through your whole codebase, adding yet another underscore to all of your switch statements!

Another serious flaw of the enum strategy is that we can’t represent a single case outside the context of the whole enum type. For instance, if we created an ImagePostComposer, we wouldn’t be able to just return the information for an image post. We’d instead have to return a Post, and then switch on that, leaving us unsure of how to handle the other cases:

let post = imagePostComposer.createPost()

switch post {
    case let .image(text, image):
        // Do something with the post
    default:
        // How should we handle the other cases?
}

Ok, so maybe an enum isn’t the best choice after all. Let’s look at another common way to structure this type of data, using struct`s.

Structs

We can instead model our feed as a collection of structs, like this:

struct TextPost {
    let text: String
}

struct ImagePost {
    let text: String
    let image: UIImage
} 

struct ArticlePost {
    let text: String
    let articleUrl: URL
}

This approach fixes a bunch of the issues that we had with enums.

• We can easily extend the model for a post type and we won’t have to add lots of underscores to our switch statements.
• We can write code that deals with a single post model. For instance, our ImagePostComposer could return an ImagePost.

Creating table view cells looks like this:

func cellForRow(at indexPath: IndexPath) -> UITableViewCell {
    let post = posts[indexPath.row]
    
    if let textPost = post as? TextPost {
        let cell = tableView.dequeueCell(“TextCell”)
        cell.configure(textPost)
        return cell
    } else if let imagePost = post as? ImagePost {
        let cell = tableView.dequeueCell(“ImageCell”)
        cell.configure(imagePost)
        return cell
    } else if let articlePost = post as? ArticlePost {
        let cell = tableView.dequeueCell(“ArticleCell”)
        cell.configure(articlePost)
        return cell
    } else {
        fatalError(“Unknown cell type”)
    }
}

This approach feels a bit easier to work with than the enum example. We no longer have to unpack each field from the enum case and pass it to the cell separately, instead we can just pass the whole post model.

So is a collection of structs better than an enum then? I’d say so, but whilst this is better in a some ways than the enum, we’ve lost something too. We’re now unable to switch over our post types. We’ve got to add that fatalError in for the default case. We’ve lost exhaustiveness.

This is going to be a problem if we want to add a new post type later on (for instance, a VideoPost). We’re going to be hitting those fatalErrors a lot!

What we want is a way to represent an exhaustive set of structs, and have the compiler warn us when we haven’t considered all cases at compile time, rather than crashing at run time. But we can’t exhaustively switch on a collection of structs, right? Or can we?

Combining the two approaches

enums give us exhaustiveness. structs give us scalability, and the ability to pass around a single case’s data in a way that isn’t tied to other cases.

We can combine these two approaches to get the best of both worlds. We’ll create a Post enum like we did before, and for case we’ll create an associated model struct.

struct TextPostModel {
    text: String
}

struct ImagePostModel {
    text: String
    image: UIImage
}

struct ArticlePostModel {
    text: String
    articleUrl: URL
}

enum Post {
    case text(TextPostModel)
    case image(ImagePostModel)
    case article(ArticlePostModel)
}

Let’s see how that looks when we create our table view cells. Note that we don’t need to extract every field of each case separately this time, we can just pass the model directly to the table view cell:

func cellForRow(at indexPath: IndexPath) -> UITableViewCell {
    let post = posts[indexPath.row]
    switch post {
        case .post(let model):
            let cell = tableView.dequeueCell(“TextCell”)
            cell.configure(model)
            return cell
        case .image(let model):
            let cell = tableView.dequeueCell(“ImageCell”)
            cell.configure(model)
            return cell
        case .article(let model):
            let cell = tableView.dequeueCell(“ArticleCell”)
            cell.configure(model)
            return cell
    }
}

Let’s look at what we’ve achieved:

• We’ve restored exhaustiveness, if we add another post type the compiler will tell us that we need to consider it in our switch statement.
• We still have a separate model object that represents each post type (eg. ArticlePostModel). We can pass this to objects that only deal with article posts, like our ArticleCell, and we don’t have to unpack them in the process. Or we can return an ImagePostModel from our ImagePostComposer.

Leveraging Protocols

Now we have a model for each post, we can also leverage the power of protocols to write more readable code. Remember the example from earlier about creating a feed that only showed images? We can easily build this by conforming some of our models to an ImageProvider protocol:

// Creating a convenience to grab the models will often come in handy
extension Post {
    var model {
        switch self {
            case .text(let model) { return model }
            case .image(let model) { return model }
            case .article(let model) { return model }
        }
    }
}

let images = posts.compactMap { ($0.model as? ImageProvider).image }

The key difference with this setup rather than the ‘enum with associated types’ setup is that we can conform to protocols on the case level. For instance, an ’image’ post, an ’image carousel’ post, and a ‘album’ post could all adopt the ImageProvider protocol, allowing us to easily extract all of the images from all ImageProvider models.

Conclusion

enums provide us with exhaustiveness. Any time we need to model a finite set of types they’re a good fit. Associated values are also great for simple requirements, but they don’t scale well, and having too many leads to code that’s difficult to read.

structs provide a way to model each case individually outside of the context of the other types. This allows us to easily pass around the data associated with a case, and create code that only deal with that single type. Structs also give our data structure (I guess the clue’s in the name!), leading more readable and maintainable code, and the ability to adopt protocols on a case by case basis.

Recently this ‘enum of structs’ pattern has been my go to starting point for modelling this type of data. Most commonly it’s been useful for table view data sources. I’ve found it to be a good pattern for providing type safety, exhastiveness and helping manage complexity. Hopefully it might work for you too!

I think that much of the difficulty in creating testable tables stems from a pattern where we have model objects that describe our application’s domain, which we then try to show in a table. Whilst these models describe a particular concern of the application’s domain perfectly, they might not fully describe the content that we want to show in a particular table cell.

Let’s have a look at an example, and then we’ll see how we can improve things. I’m going to use a table view because it’s a little simpler, but you can apply these techniques to a collection view too.

Tables showing domain models

You probably have some model objects in your application that describe the domain that your app is concerned about. For example, if you make a social networking app you might have User, Friend and Message objects. You probably obtain these objects by creating them from Json representations that you get from your api, and use them throughout your application to model the application’s domain.

For our example we can imagine a music streaming application, with a screen for a particular artist that displays all of the tracks that can be played for that artist. We probably already have a domain object Track, so we can just get all of the Tracks for the artist, and show them in a table:

struct Track {
  let id: String
  let title: String
  let duration: Double
  let streamURL: URL
}

class TrackCell: UITableViewCell {
  func configure(track: Track) {
    // configure the cell with the track
  }
}

Ok, not bad! When the user opens the artist page, we’ll fetch the Tracks from our MusicAPI, and show them in the table. The cell can then show the track title and duration, and when the user presses play we can start streaming.

With this setup we go straight from Domain Models (Track) to UITableViewCells.

This strategy breaks down though when we have to display information in our cell that isn’t described by the Track object. Let’s imagine that we have a new requirement - Our application can now download tracks and we need to show the downloaded state of each track in the list.

Our UI will look something like this. In this example the third track has been downloaded but the others haven’t.

Unfortunately our Track model now isn’t going to fully describe everything that a TrackTableViewCell needs to know. We get the Tracks from our MusicAPI, but we need to consult our DownloadsManager to find out if a track is downloaded locally or not.

Perhaps We could call out to the DownloadsManager when we create the cell and pass it the download state separately, or even call it from within the cell itself, like this:

class TrackCell: UITableViewCell {
  func configure(track: Track) {
    // configure the cell with the track
    downloadIcon.showDownloaded = DownloadsManager.hasDownloaded(track)
  }
}

It’s pretty difficult to test that our cell is showing the correct information though:

• We can test that the MusicAPI returns the correct tracks.
• We can test that the DownloadsManager reports the correct downloaded state for a track.
• But we can‘t test that a cell that is showing a downloaded track would actually show that track as having been downloaded.

This is because the code that coordinates between the MusicAPI and the DownloadsManager is now in the UI portion of our app, which is really difficult to test. Our unit test would have to create an instance of the view controller that owns the table, scroll the table to ensure the cell that we want to inspect has been created, and reach in a check the state of its views (which should really be private anyway).

There must be a better way! Let’s look at how we can make this table more testable.

Making Cell Models

Rather than using domain models to configure our cells, we’ll make a TrackCellModel that will fully describe the information that needs to be displayed in a cell, including the download state.

struct TrackCellModel {
  let title: String
  let duration: String
  let isDownloaded: Bool
}

class TrackCell {
  func configure(model: TrackCellModel) {
    // configure the cell
  }
}

A TrackCellModel provides the cell with the title, duration, and download state. Notice how we’ve already formatted the duration in to a String - We’re going to display it in a text field, so this makes sense. We’ll also benefit from pushing this processing up to the data source, that way we’ll be able to easily test it (more on that soon).

With this setup we go from Domain Models (Track) to Cell Models (TrackCellModel) to UITableViewCells.

Where do these cell models get created though? Let’s look at an example flow:

The ArtistTableDataSource calls the MusicAPI to get the Tracks. It then asks the DownloadsManager for the download state of each Track, and builds TrackCellModels with this information.

Our ArtistTableDataSource is now completely decoupled from the UI, simply providing an array of TrackCellModels to be displayed. All that’s left is to create a UITableViewDataSource that can create the relevant cell to display each cell model, and configure that cell with the model.

With this setup, the actual UITableViewDataSource is simply a lightweight translation layer from TrackCellModel to UITableViewCell, so I often find it ok to just let the view controller fill this role.

Testing

Now that we have a full table representation that is described by simple model objects, we can easily write tests that verify the content of the table. We’ll simply test the output of the ArtistTableDataSource, before the UITableViewCells would even be created.

A test that verifies that the download state is correctly displayed might look like this:

func testArtistCellDisplaysCorrectDownloadState() {
  let mockMusicAPI = MockMusicAPI()
  mockMusicAPI.returnTracksWithIds([“a”, “b”, “c”, “d”])
	
  let mockDownloadsManager = MockDownloadsManager()
  mockDownloadsManager.downloadedTrackIds = [“a”, “d”]
	
  let dataSource = ArtistTableDataSource(musicAPI: mockMusicAPI,
                                 downloadsManager: mockDownloadsManager)
  dataSource.reload()
	
  // Verify that the table will show tracks ‘a’ and ‘d’ as downloaded
  XCTAssertTrue(dataSource.cellModels[0].isDownloaded)
  XCTAssertFalse(dataSource.cellModels[1].isDownloaded)
  XCTAssertFalse(dataSource.cellModels[2].isDownloaded)
  XCTAssertTrue(dataSource.cellModels[3].isDownloaded)
}

Using this technique we can ensure that a table that is built from multiple sources of information will display the correct data.

We can scale this solution as our table’s data becomes more complex. For instance, we might also add the ability for a user to favourite a track, and we want to show if each track is favourited. The ArtistTableDataSource could also check with the FavouritesManager for each track and set an isFavourited flag on the TrackCellModel which we can then verify in a test.

Staying Humble

The humble object pattern helps us make our code testable by keeping the complexities in our code in the parts of the codebase that we can test, and making the parts that we can’t so simple that they don’t require testing.

There’s no good way for us to test that an actual UITableView is showing the correct UITableViewCells and that all of those cells have the correct content. It’s far easier for us to build an array of TrackCellModels, each which completely describes a cell’s content, and write a test suite that verifies that those models contain the expected configurations for each cell given a range of inputs.

To make our table as humble as possible we need to perform as little calculation in the actual UITableViewCell as possible (the untestable portion of our flow). We’ll achieve this by just performing simple binding of the TrackCellModel’s data to the views of the cell, and pushing all of the hard work to the ArtistTableDataSource.

For example, when you pass a domain model to your cell it might contain a Date which you then convert to a String using a DateFormatter inside of the cell. Using cell models, we can increase the testability of our table by converting the domain models’s Date to a String before giving it our cell model. We can then test that the date formatting is being applied correctly on the cell model, and in the actual cell itself we’ll just bind that string to a UILabel.

Thinking Bigger

By creating a testable dataSource, we can not only test the configuration of individual cells, but the content of the table as a whole. For instance, we might give the user the ability to change the sorting order of the tracks, by most popular, or newest. We could write a test that creates an ArtistTableDataSource connected to a mock MusicAPI, sets the sorting order, and verifies that the TrackCellModels that are produced appear in the correct order.

Here’s how we might test an alphabetically ascending sorting option, for instance:

func testAlphabeticalOrdering {
  self.mockMusicAPI.returnTracksWithTitles([“Wonderwall”, “Hello”, “Supersonic”])
  self.dataSource.sortMode = .alphabeticalAscending
  dataSource.reload()
	
  XCTAssertEqual(dataSource.cellModels[0].title, "Hello")
  XCTAssertEqual(dataSource.cellModels[1].title, "Supersonic")
  XCTAssertEqual(dataSource.cellModels[2].title, "Wonderwall")
}

We can also expand our model to include different cell types. Alongside showing the tracks for a specific artist, we might want to show playlists that feature that artist and related artists. We’ll have a separate cell for each of these. Our model might look like this:

enum ArtistCellModelType {
  case track(TrackCellModel)
  case playlist(PlaylistCellModel)
  case relatedArtist(RelatedArtistCellModel)
}

Our ArtistTableDataSource will now produce an array of ArtistCellModelTypes.

We can now write a test that verifies that specific cells appear in the correct places in the table. The following test verifies that a playlist cell will be shown under the track cells:

func testPlaylistAppearsOnArtistPage {
  self.mockMusicAPI.returnTracksWithIds([“a”, “b”, “c”])
  self.mockPlaylistAPI.returnPlaylistsWithName([“Top Hits”])
  self.dataSource.reload()
	
  // Adding convenience extensions on ArtistCellModelType makes our tests much easier to read
  XCTAssertTrue(dataSource.cellModels[0].isTrack(withId: "a"))
  XCTAssertTrue(dataSource.cellModels[1].isTrack(withId: "b"))
  XCTAssertTrue(dataSource.cellModels[2].isTrack(withId: "c"))
  XCTAssertTrue(dataSource.cellModels[3].isPlaylist(withName: "Top Hits"))
}

The test was made much more readable due to the extensions on ArtistCellModelType. This type of extension is just for testing so can be declared in your testing target. As your table’s data becomes more complex I find that maintaining a good set of these extensions helps keep the tests short and understandable.

There’s plenty more that we can do too.

• Perhaps the user can favourite tracks, and favourited tracks appear at the top of the list. By passing a MockFavouritesManager to our datasource, we can mark some track IDs as favourited and verify that they appear first in the array.
• Perhaps we add a feature whereby for younger users, tracks with explicit lyrics are filtered out of the list. We can initialise our ArtistTableDataSource with a User that has an age where this feature is enabled. We can then tell our MockMusicAPI to return tracks with the containsExplicitLyrics flag set to true, and verify that our data source doesn’t include these tracks in the table.

I’ve been using the ‘cell model’ approach for my table views and collection views recently and have found it to be a great pattern to increase testability. Having a full representation of the table’s content as model objects makes it easy to write tests that verify that individual cells contain the correct content, and also that the overall structure of the table is as we expect. I hope that you find it useful too!

Pretty quickly I came to the realisation that most Swift developers come to - that the awesomeness of Optionals is actually in types being NON-Optional. You acquire some kind of resource that may or may not exist (such as the contents of a file), unwrap it, and then from that point onwards frolic in a utopia of non-optionalness, without a null pointer exception in sight.

For the most part, I viewed Optionals kind of like little gremlins. Your aim is to contain and confine those little gremlins to small parts of your codebase, ridding yourself of them as quickly as possible, so that they can’t wreak havoc anywhere else.

I think this is a pretty good way to approach Optionals. Recently though, I’ve come to realise that non-optionalness isn’t always helpful, so here’s some tricks where intentionally using a bit of Optionality might actually be helpful:

Optional Array Access

Here’s the brief. We’re making the leaderboard for a game, and any number of players could be on the leaderboard. Crucially, the first, second and third place players will be displayed on a podium at the top of the leaderboard.

We’ve got a method that can populate the podium, taking three optional Players:

func showPodium(first: Player?, second: Player?, third: Player?) {}

We’ll pass the first three players from our players array to this method. There might not be three players on the leaderboard yet though, so we have to check that each player exists before we grab it from the array:

var players = getLeaderboardPlayers()

var firstPlayer: Player?
if players.count > 0 {
	firstPlayer = players[0]
}

var secondPlayer: Player?
if players.count > 1 {
	secondPlayer = players[1]
}

var thirdPlayer: Player?
if players.count > 2 {
	thirdPlayer = players[2]
}

showPodium(first: firstPlayer, second: secondPlayer, third: thirdPlayer)

We don’t know how many players will be in the array, so before each access we check that the array has enough items so that we don’t crash. Notice as well how we’re also technically violating the DRY principle because for each access we had to define the index twice.

Any exception can be traded for an Optional though. Simply check for the exception condition, and return nil if it fails.

We’ll define a subscript on Array that returns nil if the index is out of bounds:

extension Array {
    
    public subscript(maybe index: Int) -> Element? {
            if index > count - 1 {
                return nil
            } else if index < 0 {
                return nil
            } else {
                return self[index]
            }
    }
}

Let’s see if that can improve our code:

var players = getLeaderboardPlayers()
showPodium(first: players[maybe: 0], 
					 second: players[maybe: 1], 
					 third: players[maybe: 2])

That’s so much better. Using Optionals actually made our code easier to read and understand!

Optional Array appending

Ok, new brief. We’re making a navigational menu. It’s a list of links that open other pages of our application, that we’ll use a tableview to display.

The only issue is that what items show in the menu depends on the state of user. A user might be logged in, upgraded, and have some number of credits. So we end up with something like this:

var menuItems: [String]

if user.isLoggedIn {
    menuItems.append("Manage Account")
} else {
    menuItems.append("Login")
}

if !user.isUpgraded {
    menuItems.append("Purchase Upgrade")
} else {
    menuItems.append("Manage purchases")
}

if user.numberOfCredits < 10 {
    menuItems.append("Purchase additional credits")
}

This is ok, but it’s getting a bit messy. As it grows it will become difficult to see how the menu is ordered. What we really want is a ordered list of possible elements that will appear in the menu if they are applicable to the user, and to hide all the additional logic elsewhere.

Let’s make another maybe function, but this time for appending to an array:

extension Array {
    mutating func append(maybe item: Element?) {
        if let item = item {
            append(item)
        }
    }
}

Now we can rewrite our example to make use of it:

var menuItems: [String]

menuItems.append(maybe: makeManageAccountItem())
menuItems.append(maybe: makeLoginItem())
menuItems.append(maybe: makePurchaseUpgradeItem())
menuItems.append(maybe: makeManagePurchasesItem())
menuItems.append(maybe: makeAdditionalCreditsItem())

// Each 'make' method returns an optional
func makeManageAccountItem() -> String? {
    return user.isLoggedIn ? "Manage Account" : nil
}

Each make method returns a String?, which will be nil if that option shouldn’t appear in the menu for the current user.

This gives us a declarative list of elements that could appear in the menu. The order is obvious from the code, and all of the conditions are handled elsewhere. Sure, we purposefully added some optionality to our code, but because we now have purpose built extensions for dealing with optionals, there’s not an if let in sight!

Conclusion

In general we want things to be non-optional where possible. The Optional type is designed to model a situation where something may or may not exist, though, and if this is what our code needs then we shouldn’t be afraid to use it.

The important thing is to build the mechanisms to work with optionals in a convenient way. Once these are in place, we can sometimes use optionality to our advantage to write more readable code.

But there’s a new pattern that seems to be quietly replacing the delegate pattern. I’m not sure if it has an official name, but I call it:

The Closure Callback Pattern

You probably know which one I mean, but in case you need a refresher, here’s the delegate way of doing things:

protocol ImageDownloaderDelegate: class {
    func imageDownloader(_ downloader: ImageDownloader, didDownloadImage image: UIImage)
}

class ImageDownloader {
    
    weak var delegate: ImageDownloaderDelegate?
    
    func downloadImage(url: URL) {
        // download the image asynchronously then...
        delegate?.imageDownloader(self, didDownloadImage: theImage)
    }
}

and here’s the closure callback way:

class ImageDownloader {
    
    var didDownload: ((UIImage?) -> Void)?
    
    func downloadImage(url: URL) {
        // download the image asynchronously then...
        didDownload?(theImage)
    }
}

Like everyone else, when Swift came out I dabbled with the closure callback pattern, using it where I might have previously used a delegate in a quest for ever increasing ‘Swifty-ness’. I was left unsatisfied though. Sometimes it felt like an improvement, and sometimes it didn’t. Is the delegate or the closure callback the superior pattern? I guess, well, it depends.

Depends on what, though??? Let’s compare these two approaches and see if we might learn something.

Breaking the retain cycle

Whenever two objects reference each other, one of them has to hold a weak reference to the other or we get a retain cycle. The handling of this couldn’t be more different between these two patterns.

How the delegate pattern does it:

class ImageDownloader {
    weak var delegate: ImageDownloaderDelegate?
    //...
}

class ImageViewer: ImageDownloaderDelegate {
    
    let downloader: ImageDownloader()
    
    init(url: URL) {
        downloader.delegate = self
        downloader.downloadImage(url: url)
    }
    
    func imageDownloader(_ downloader: ImageDownloader, didDownloadImage image: UIImage) {
        // view the downloaded image...
    }
}

• The ImageDownloader is responsible for breaking the retain cycle by holding a weak reference to it’s delegate
• The weak / strong relationship only has to be defined in a single place
• Convention is for delegates to be held weakly, and a linter like SwiftLint will warn you if you forget to do this

How the closure callbacks do it:

class ImageDownloader {
    var didDownload: ((UIImage?) -> Void)?
	//...    
}

class ImageViewer {
    
    let downloader: ImageDownloader
    
    init(url: URL) {
        downloader = ImageDownloader()
        downloader.downloadImage(url: url)
        downloader.didDownload = { [weak self] image in
            // view the image
        }
    }
}

• The ImageViewer is responsible for making sure that it’s references itself weakly in the callback
• The weak / strong relationship must be correctly implemented in every callback
• It’s easy to make a mistake a cause a memory leak

It may be the old way of doing things, but the delegate pattern is a clear winner on this front. The weak relationship is only defined once, and it’s much harder to make a mistake.

There’s plenty more to consider though, let’s see if the closure callbacks can redeem themselves…

One to many relationships

What if one class needs use multiple ImageDownloaders, how might our two patterns fair then?

First up, the delegate pattern:

class ProfilePage: ImageDownloaderDelegate {
    
    let profilePhotoDownloader = ImageDownloader()
    let headerPhotoDownloader = ImageDownloader()

    init(profilePhotoUrl: URL, headerPhotoUrl: URL) {
        
        profilePhotoDownloader.delegate = self
        profilePhotoDownloader.downloadImage(url: profilePhotoUrl)
        
        headerPhotoDownloader.delegate = self
        headerPhotoDownloader.downloadImage(url: headerPhotoUrl)
    }
    
    func imageDownloader(_ downloader: ImageDownloader, didDownloadImage image: UIImage) {
        
        if downloader === profilePhotoDownloader {
            // show the profile photo...
        } else if downloader === headerPhotoDownloader {
            // show the profile photo...
        }
    }
}

We have to check which instance of the ImageDownloader is calling us in each callback. If you have a whole bunch of delegate methods this is going to get really tedious. Plus you’re likely to make a mistake.

I’m sure we’ve all worked on an app before where the same object was the delegate for multiple UITableViews. Not cool.

Let’s see if the closure callback pattern can save us:

class ProfilePage {
    
    let profilePhotoDownloader = ImageDownloader()
    let headerPhotoDownloader = ImageDownloader()
    
    init(profilePhotoUrl: URL, headerPhotoUrl: URL) {
        
        profilePhotoDownloader.didDownload  = { [weak self] image in
            // show the profile image
        }
        profilePhotoDownloader.downloadImage(url: profilePhotoUrl)
        
        headerPhotoDownloader.didDownload  = { [weak self] image in
            // show the header image
        }
        headerPhotoDownloader.downloadImage(url: headerPhotoUrl)
    }
}

It’s a clear win. The callbacks for the two instances are completely separate, so there’s no chance of us getting them mixed up.

The closure callbacks win this one. It’s 1-1. Let’s see what’s next:

Datasources

Ok, these aren’t strictly delegate patterns, but I’ve seen the closure callbacks used to supply information to an object too, so I’m including them.

Lets look at a protocol based datasource pattern:

protocol SerialImageUploaderDataSource: class {
    var numberOfImagesToUpload: Int { get }
    func image(atIndex index: Int) -> UIImage
    func caption(atIndex index: Int) -> String
}

class SerialImageUploader {
    
    weak var dataSource: SerialImageUploaderDataSource?
    
    init(dataSource: SerialImageUploaderDataSource) {
        self.dataSource = dataSource
    }
    
    func startUpload() {
        
        guard let dataSource = dataSource else { return }
        
        for index in 0..<dataSource.numberOfImagesToUpload {
            let image = dataSource.image(atIndex: index)
            let caption = dataSource.caption(atIndex: index)
            upload(image: image, caption: caption)
        }
    }
    
    func upload(image: UIImage, caption: String) {
        // Upload the image...
    }
}

• The protocol methods are all required, so if the dataSource exists, then we know that it has implemented all of the methods that we require
• We passed the data source in to the init method, so we’re making it clear to the user of this class that a data source is required
• If we add required methods to the datasource protocol later, we’ll get a compiler error until we implement them

Now a Datasource implemented with closures:

class SerialImageUploader {
    
    var numberOfImagesToDownload: (() -> Int)?
    var imageAtIndex: ((Int) -> UIImage)?
    var captionAtIndex: ((Int) -> String)?
    
    func startUpload() {
        
        guard
            let numberOfImagesToDownload = numberOfImagesToDownload,
            let imageAtIndex = imageAtIndex,
            let captionAtIndex = captionAtIndex
            else {
                return
        }
        
        for index in 0..<numberOfImagesToDownload() {
            let image = imageAtIndex(index)
            let caption = captionAtIndex(index)
            upload(image: image, caption: caption)
        }
    }
    
    func upload(image: UIImage, caption: String) {
        // Upload the image...
    }
}

This one’s a bit of a train-wreck. We rely on all three closures being non-nil, so I had to guard against all of them. I could have passed them all in the init and made them non-optional, but I think that would be a bit ridiculous.

If you just require a single closure then you can supply it in the init as a non-optional, otherwise using a protocol is clearly the better approach.

Scalability

So, we’ve just got one method now, but what if we have 10 in the future? Our protocol now looks like this:

Delegate:

protocol ImageDownloaderDelegate: class {
    func imageDownloader(_ downloader: ImageDownloader, didDownloadImage image: UIImage)
    func imageDownloaderDidFail(_ downloader: ImageDownloader)
    func imageDownloaderDidPause(_ downloader: ImageDownloader)
    func imageDownloaderDidResume(_ downloader: ImageDownloader)
}

extension ViewController: ImageDownloaderDelegate {

    func imageDownloader(_ downloader: ImageDownloader, didDownloadImage image: UIImage) {
    }
    
    func imageDownloaderDidFail(_ downloader: ImageDownloader) {
    }
    
    func imageDownloaderDidPause(_ downloader: ImageDownloader) {
    }
    
    func imageDownloaderDidResume(_ downloader: ImageDownloader) {
    }
}

• We’ve got all of the delegate methods neatly wrapped up in an extension
• It’s really clear how all of this works

Closure callbacks:

class ImageDownloader {
    var didDownload: ((UIImage?) -> Void)?
    var didFail: (() -> ())?
    var didPause: (() -> ())?
    var didResume: (() -> ())?
}

class ViewController: UIViewController {
    
    let downloader = ImageDownloader()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        downloader.didDownload = {
            //...
        }
        
        downloader.didFail = {
            //...
        }
        
        downloader.didPause = {
            //...
        }
        
        downloader.didResume = {
            //...
        }
    }
}

I don’t like this at all. It’s not clear where we should even put the setup code for all the callbacks. Maybe we could make a method called setupDelegateCallbacks()? It’s all a bit messy for my liking.

Another win for the delegate pattern.

And on to our last test!

Enforcing the contract

Any type that works with another type should expect the other type to adhere to a contract. That way, if that contract isn’t fulfilled then the compiler can let us know at compile time, and we can avoid nasty surprises at runtime.

Lets look at how type-safe these two approaches are.

Delegates:

Add a new method, get a compiler error, sweet!

Closures callbacks:

Add a new callback and you’ll be blissfully unaware that you haven’t implemented it. Which might have bad consequences. Hope it wasn’t important!

So which is better?

So which is best? As we already knew, it depends! But hopefully we have a better idea on what now, so lets try to lay down some guidelines:

Scenario 1:

You have a single callback

The callback closures pattern is the best here. Pass it in the initialiser, and you can even make it non-optional:

class ImageDownloader {
    
    var onDownload: (UIImage?) -> Void
    
    init(onDownload: @escaping (UIImage?) -> Void) {
        self.onDownload = onDownload
    }
}

Scenario 2:

Your callbacks are more like notifications

If your callbacks are more like ‘notifications’ or ‘triggers’ that fire when other things happen, then the closure callbacks can be a less invasive option. Keep them optional, and you can just implement the ones that you are interested in.

If your delegator is saying Hey I just did this thing btw, letting you know, rather than I really need you to do something now! an optional closure can let you subscribe to that callback if you need it, or not if you don’t.

Scenario 3:

You need to become the delegate to multiple instances

The closure callback is the better pattern here. Be careful that this is really what you require though. You can always have an object that is a dedicated delegate or datasource, and have many instances of those.

Scenario 3:

Your delegate is actually a datasource

Use a protocol, it enforces a stronger contract between the two types, and the compiler can help you find bugs.

Scenario 4:

Your have many callbacks, and they might change in the future

Use a protocol. If you forget to implement new methods in the future, the compiler will tell you rather than your users.

Anything else, or you’re not sure:

Anything else, or you’re not sure

If in doubt, use a protocol. Defining a protocol guarantees that conforming types will have implemented the specified methods. If the protocol requirements change the future, the compiler will require you to update your types. It also simplifies the weak / strong relationship, allowing you to define it in a single place.

Conclusion

The callback closures pattern seems to be creeping in everywhere. It can be a great way to reduce complexity, handle one to many relationships, and make code more readable. I still think that a protocol is more appropriate for the majority of cases, though.

Choose the write tool for the right job, and if you only remember one thing from this post - never become the delegate to two UITableViews!

Further reading

This post by Oleg Dreyman presents a nice solution for avoiding the pitfalls of the weak / strong dance using closure callbacks

This post by John Sundell has some nice examples of closure callbacks vs. delegates.

// This is a really long comment that describes something important, but it either goes off the edge of the screen, or Xcode wraps it a the edge of the editor

This comment isn’t that easy to read. There’s a good reason why newspapers write in columns, and websites show articles in a narrow strip in the middle of your screen - It’s hard to read long horizontal text!

It would be better if our comment looked like this:

// This is a really long comment that describes something
// important, but it either goes off the edge of the screen,
// or Xcode wraps it a the edge of the editor

This comment wraps at 60 characters. As long as your monitor can display 60 characters across then it will look the same whether you’re reading on a 12 inch display or a 27 inch one, and it’s much easier to read.

If you take a look at the documentation for the swift standard library, Apple also use this formatting technique

Formatting your own comments like this usually just requires writing the whole comment out first, then just going though and adding the line breaks and the // prefix to each line. A few extra key strokes but no biggie.

But then, inevitably, you have to edit it.

This requires having to undo all of the wrapping, insert the new text, move words to different lines, reinsert the line breaks in new positions. It’s a world of pain.

The Solution

It sounds like we need an automated solution for this! Xcode doesn’t provide one, so I decided to write my own. Xcode Source Editor Extensions (yeah, remember those?) are actually a perfect fit for this.

Simply write out your comment, select ‘wrap’ and:

And if you want to edit an already wrapped comment? ‘Re-wrap’ has got you covered:

There’s a few other handy features too:

• Comment prefixes are maintained (eg. ‘//’ or ‘///’)
• Maintains indenting
• If you’re wrapping documentation, code examples won’t be wrapped

Check out Comment wrapper on GitHub or download on the app store

1.0 (1)

This is version number 1.0, build number 1

As I’m sure you know, the build number is used to differentiate different builds of the same version, so you might upload build 1, then make amendments, and then upload build 2

I used to manually increment this build number each time I created a build, but that strategy has it’s problems:

• iTunes Connect will reject builds that have the same build number as a previously uploaded build. So you can waste a load of time if you forget to increment the build number.
• Sometimes I couldn’t remember if I’d incremented it, so would end up doing it twice
• The build number says nothing useful about this particular build

The last point is the most important. How do you know that you have the right build? QA might tell you that they found a problem on build 8… which one was that again? Or you’re submitting your app on iTunes Connect, and the build is 9 - was that the one you just created or not?

Recently I’ve been using a timestamp (yyyyMM.dd.HHmm) for my build numbers, which looks like this:

1.0 (201805.15.1407)

This build was created on 15/05/2018 at 14:07

Note that you can only have three periods in the build number, which is why I’ve put the year and month together

This has some great benefits:

• If QA want to test the changes that were built today, they can easily verify that the build time of their version looks right
• Newer builds always have higher build numbers, and it’s automated, so you don’t have to worry that a developer made a mistake
• If you upload a build to iTunes Connect and then another the next day with some changes, it’s obvious which is which one is which!

This is pretty easy to achieve using a ‘Run Script Phase’ in Xcode’s build phases with the following script:

# Generate the build number using current date and time
buildNumber=$(date "+%Y%m.%d.%H%M")

# Set the build number in plist file
/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $buildNumber" "${TARGET_BUILD_DIR}/${INFOPLIST_PATH}"