mbehan

Storyboards, Multiple Developers and Git.

An updated version of this article is available on my employer's blog

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

But storyboards can be cruel if you're not careful. Git pulls become nervy affairs, a slip merging by hand can render your storyboard unreadable by Xcode and not knowing when to stop using them can turn your lovely lines and boxes into a maintenance nightmare.

John McClane, crawling through some ducting, wishing he still used nibs

"Come to the coast, we'll get together, have a few segues"

I've worked on a bunch of apps of all shapes and sizes using storyboards over the last year or so as part of a team and we've been working on perfecting our use of them. I've been investigating and testing storyboard best practice and this is what I've learned so far.

The Precap #

(Wiktionary says it's a word)

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.

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.

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.

But you said to keep using Nibs? #

Yep, for custom views, table view cells and the like. A view can't exist outside a view controller in a storyboard so if you don't need a view controller for it you really shouldn't be adding it to a storyboard.

So what about single view controllers in Nibs then?

We've a project in which we've used some Nibs from an existing project in conjunction with a storyboard and it hasn't been a problem, but if I was making those components again now they'd be in a storyboard. Having a single view controller in a storyboard will make sense at times, and when you end up wanting to add additional screens to your account details say and all you have to do is drag a new view controller in beside the existing one and hook up a segue you'll be happy.

Multiple devs #

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 wanted to see just how careful you really have to be.

I created a simple Xcode project with a single storyboard and set out with my new git friend to put together a few screens.

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.

Test 4: Adding modified views to a Navigation Controller #

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 5: 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.

Xcode as git client you say? #

This might be more of a personal preference, and if you want to rebase rather than merge this is a not an option (for now at least) but it seems screwing up the storyboard XML is likely to happen less frequently if you don't let anything other than Xcode touch it.

A conclusion, for now #

After experimenting a little with this test project I'm happy that we can edit our storyboards simultaneously when we absolutely have to, but that shouldn't stop us planning things out so that it doesn't happen, and we'll be sticking to this list, same one as above:

Who has two thumbs and loves storyboards now? John McClane