Insight Author
Michael Behan
Principal Software Developer

Storyboards, Multiple Developers and Git

Practical tips on using storyboards in large iOS projects

February 26, 2018
Marino Insights Cover Image

Storyboards are great. You can get your app flowing in just a few minutes without writing a single line of code, you can initialise your navigation controllers ridiculously easily and just zoom out a bit and you have a lovely picture of your entire app on a single screen, with lines and boxes and everything. 

But once your app is anything beyond trivial in size, and it’s worked on by anyone but just you, storyboards aren’t a guaranteed win.

Git merges become nervy affairs, a slip resolving a conflict by hand can render your storyboard unreadable by Xcode and not knowing when to stop using them can turn your line and box filled dreams into a maintenance nightmare. 

‍“Come to the coast, we’ll get together, have a few segues”

We’ve built a lot of iOS apps since Storyboards were introduced with iOS 5 back in 2011 and over that time we’ve been refining our use of them, while Apple has been slowly improving them. If you were put off by storyboards at first it’s worth having a look at them again now. With the latest features, and our best practices in mind there’s no need to fear storyboards, even for large and complex interfaces.

How We Storyboard

  • Make sure everyone is on the same version of Xcode
  • Use multiple small storyboards
  • Use Nibs for custom views
  • Think about which storyboards are involved when assiging stories / tasks
  • Merge often

1 - Xcode

We’ve had hassle sharing storyboards across even minor versions of Xcode, storyboards created in one will do crazy stuff in another, or just plain won’t work. Don’t let anyone sneak ahead to the latest developer preview unless they’re doing a separate installation.

2 - Multiple Storyboards

But what about the lovely whole app view, all those lovely lines and boxes all perfectly arranged? That was never what storyboards were about, and you’ve still got your whiteboard for that. 

Divide and conquer is your mantra for everything else you do so it should be for storyboards too. 

It’s easier to reason about storyboards with a single purpose and devs are less likely to trip each other up if they’re not working on the same storyboards at the same time. With storyboard references available since iOS9, doing this is simpler than ever.

So how do you break it up?

Per user story is a decent approach, but that can be too granular at times. A separate storyboard for login and one for viewing an account makes sense, but maybe you should keep the lost password flow in with your login — If all you’ve got in each storyboard is a single view controller you might as well be using Nibs, the beauty of storyboards is making connections between view controllers.

3 - Using Nibs

Storyboards get all the love in Xcode updates but we still prefer Nibs for custom views, table view cells and the like. A view can’t exist outside a view controller in a storyboard so in general if we don’t need a view controller for it we don’t add it to a storyboard. As for single view controllers in Nibs, we tend to prefer storyboards for those because invariably you’ll end up adding other view controllers to it later or want to reference it from another storyboard.

4 - Multiple Developers

Even with all your concerns perfectly separated, and making sure everyone’s on the same page you’re going to end up working on the same storyboard as someone else at the same time. Having to wait for someone to give you their changes before you can do something is no fun so I created a simple Xcode project with a single storyboard and set out with a new git friend to put together a few screens to figure out just how careful you have to be.

Let's test it!

Test 1: Adding to the same empty view controller

I started off simply adding a label and having Testy add an empty Image View.

We’re working on the same view controller right away so I expected there to be a conflict to sort out and indeed there was.

The XML is clearly not intended to be parsed by human eyes but this looks straight forward enough, I can see two separate additions so accepting one followed by the other should work fine. This looks just like the kind of conflict that comes up on .xcodeproj files when two devs are adding files.

It worked, I had to look at some XML but nothing blew up, for extremely simple changes to the same view controller we don’t have to worry too much.

Test 2: Editing different view controllers

I added a lovely purple view to one view controller and had Testy add a view to a different view controller. We really shouldn’t have any problems here

And we don’t. It seems editing the same storyboard is fine so long as we keep to different view controllers. But, sometimes we might edit another view controller without meaning to, so I looked at some more scenarios…

Test 3: Rearranging parts of the storyboard that someone else changed

Here Testy has changed one of my purple boxes to green, and I’ve just been fiddling with the layout a bit, swapping the order of the 2 view controllers to the right.

This auto merged and left us looking good, it chose my layout.

When you’re inferring screen elements such as the nav bar adding a navigation controller can affect a bunch of view controllers that someone else might have been working on. Here I’ve added a navigation controller while Testy’s been changing some colours.

To my surprise this auto merged just fine, the views that Testy was working on got the nav bar. It makes sense if you take a look at the XML, no nav bar is added as a child of the view controllers, the inferred setting is in there and Xcode knows what to do with that.

Test 4: Making changes to a slightly more filled out view controller

Things have gone ok so far, so lets revisit editing the same view controller, this time making it a bit more realistic.

We both started off with this:

All I did was enclose the label in a scroll view, Testy had a few more bits and pieces to do, he changed that label from an attributed label to a regular label, moved it, changed its text and changed the background colour of the view for good measure. We know we’re going to be looking at XML here but that wasn’t a problem before.

And some of the XML here isn’t so bad either.

But it’s clear that as soon as you make more than 1 simple change you’ve got a problem, and you could easily waste a lot of time dealing with it.

The order of of XML has changed between the versions significantly, and it doesn’t seem to be too smart at highlighting which parts are the same. For example I didn’t touch the table view in either revision but Xcode highlighted it being removed on one side and added in again in the middle of a bunch of other stuff later on.

It ended up only taking a few minutes to figure this example out and getting to a version that made sense including both sets of changes but I was hand editing the XML and that is dangerous. It’s clear that if you make more than a few changes and keep them for yourself for too long, you could end up in a bad way pretty quickly.

Conclusion

This little experiment shows you don’t have to fear editing storyboards simultaneously, but that shouldn’t stop you planning things out so that it doesn’t happen often, and we’ll be sticking to this list, same one as above:

  • Make sure everyone is on the same version of Xcode
  • Use multiple small storyboards
  • Use Nibs for custom views
  • Think about which storyboards are involved when assigning stories / tasks
  • Merge often

Originally published at mbehan.com.

Take a look at our team's insights

View all our insights

Let’s chat about how we can work together to create something great

Get in touch