Storyboard Segue Identifier naming conventions

by

As with most things in programming, you can use any name you like.

But, as with most things in programming, names matter and good names are hard.

Here’s how I name segues…

Good segue names

Name segues as you would name action methods. Name segues by what they will do. Good segue name examples:

  • addUser
  • showReport
  • editAccount
  • composeMessage
  • reviewChanges

Bad segue names

Avoid segue names that just describe what the segued to thing is or how it works.

Some examples of bad segue names!!:

  • Bad name 1! – segueUserDetailViewController – avoid this!
  • Bad name 2! – segueImageViewController – avoid this!
  • Bad name 3! – RecipeViewControllerToIngredientViewController – avoid this!

Why are these names bad?

These names are bad because they explicitly state their implementation. Instead of naming what they do, they name how they do it. This is a form of coupling.

So, if what you are doing is “showing a shopping basket”, the fact that this happens to be done by presenting a ZZBasketViewController today, is totally irrelevant to the caller, and just burdens them with detail they don’t care about. Perhaps tomorrow it’ll be done with a ZZShoppingItemsViewController or an STSuperConfigurableStuffList.

So:

  • Use a name such as showShopping.
  • Avoid a name such as showBasketViewController.

A naming rule for all your programming

Usually the point of an abstraction is that a user doesn’t and shouldn’t know how the abstraction works. All they know is what it will do for them – what it means to them.

It is bad for any abstraction’s name to needlessly specify how something must be done because then the caller prescribes how the callee must work.

This coupling will:

  • Burden the caller with knowledge it does not need.
  • Arbitrarily constrain the callee’s implementation in a needless way.
  • Couple the caller to the callee in a pointless and costly way requiring maintenance or future removal.

If someone subsequently ignores the coupling and changes the implementation, then the given name begins to lie and will mislead a future programmer who looks at the code, unless the name is also changed.

Segues are abstractions. Segue names should not refer to the implementation.

Follow Cocoa’s identifier convention

Both Swift and Objective C use camelCase for identifiers.

  • Names never contain _ or - characters.
  • With the exception of types, classes & protocols, all names should have a lower case first letter.

Name your segues in camelCase and give them a lower case first letter.

Uniqueness is not necessary

Segue names do not need to be unique within a storyboard. The names only need to be unique within a particular scene (view controller).

Ilea’s answer mentions this, quoting from Ray’s site:

It only has to be unique in the source scene; different scenes can use the same identifier.

…in fact, it often makes a lot of sense to have the same segue name in many scenes of a storyboard because you might be able to addLocation from a number of scenes.

Further tips for naming and working with Segues…

Scenes can have >1 segue going to the same other scene

This is something that I use a bit. You might have a view controller that can display and also edit account information: AccountVC. Nothing stops you having two or more segues from a scene that go to this same other view controller’s scene: editAccount and showAccount. Your prepareForSegue:sender: can then use the segue ID to set up the AccountVC appropriately to either edit or just show.

Use the sender

Because segues are called with a sender, they feel very much like action messages.

Make use of the segue’s sender to configure the destination view controller in your prepareForSegue:sender: implementation. This saves polluting your view controller with transitory state for this.

Here’s an example of a table view delegate handling a tap:

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
  Account *const account = [self accountAtIndexPath: indexPath];
  [self performSegueWithIdentifier: showAccount sender: account];
}

Which lets your prepare… method look like this:

- (void)prepareForSegue:(UIStoryboardSegue *)segue sender:(id)sender
{
  if([showAccount isEqualToString: segue.identifier])
  {
    AccountViewController *accountVC = segue.destinationViewController;
    accountVC.account = sender;
  }
}

Avoid @"stringLiterals" in performSegue: calls

If you’re asking “What’s this showAccount? You mean @"showAccount", right?”. A big tip is: Use file scope variables for your segue names. Do not use @"string literals". So, at the top of my view controllers there’s often a block like this:

DEFINE_KEY(showReport);
DEFINE_KEY(showPDF);
DEFINE_KEY(shareReport);

The macro DEFINE_KEY is in my project’s .pch and looks like this:

#define DEFINE_KEY(keyName) static NSString *const keyName = @#keyName

… it creates a const NSString* variable who’s value is equal to its name. The static means that it’s only available in this “compilation unit” and doesn’t pollute the global name space at link time.

If you use a variable like this, you have the compiler on your side. You can’t get a name wrong because then it won’t build. Code completion will help you finish a name that you start. You can refactor a name as you would any other variable. Even the syntax highlighter is on your side!

Think of unwind segues as like exceptions

Think of the destination view controller as being an exception handler for the unwind segue. The unwind segue propagates up the navigation stack very much like an exception propagates up the call stack. The segue looks for an unwind handler like an exception looks for an exception handler (catch block). It’s looking for an unwind handler that is suitable for the type of unwind segue – again, this is like an exception handler for the type of exception being searched for.

Importantly, you can have many view controllers implementing the same unwind handler. The unwind will bubble up like an exception to the first view controller that handles it.

The usual advice for unwind naming is something like unwindToMessageList. This can make sense, but following the “exception handler” metaphor, it can be very useful to name unwind handlers by what they are handling. So, unwindFromEventDetails, unwindFromReport, or unwindFromCloseupImage might be good names describing what is being caught. These handlers can be implemented at multiple possible catch sites. The appropriate handler will be automatically selected using the navigation hierarchy.

Leave a Comment