Ready… Set… Xcode!

As is common in every app development cycle, there comes a time when we must start setting up a project.

This normally involves mundane and boilerplate tasks such as setting up folder structures, linking up the project to the right third party libraries (if needed) and adding reusable extensions/categories/classes from earlier projects that we have grown an affection towards or have become fully dependant on. Depending on your ability, how meticulous and orderly you are with these kind of things, your team size, the project size and how important an understanding of the overall architecture is for you as developer (very important), this can take you anywhere from a couple of hours to (hopefully not more than) a day. Depending on how many applications you work on during the course of your career, these times add up to considerable numbers (make the maths in your head and cringe).

Surely there has to be a better way to skip jump this process? Well… Theoretically, you could define you own custom templates. I say theoretically mainly because of a couple of “bumps in the road”:

  • Any Apple documentation regarding how to do this is non-existent. Being Apple who they are, there must be a reason for this (such as future mutability of the SDK).
  • At the time of this writing, the only way to figure out how to set your own custom templates is to look at the pre-existing templates and try to work it out for yourself (did I mention future mutability of the SDK?).
  • There is a long history of custom templates being wiped out or directories changing on new versions of Xcode (or updates on the developer tools). So… About that future mutability… There went your few days of hard-earned work that you felt so proud about a few weeks ago. 😦

If you’re obstinate about following this path, be forewarned that you are going down a really obscure rabbit hole, and if you don’t believe me, just take a look at how project templates are structured in Xcode 6 by going to:


My advise, therefore, is: DO NOT USE TEMPLATES. Use base projects instead, they work pretty much the same way, except they are safer, can easily be changed and can be scripted. 🙂

Strategies for setting up your project

Before we dive into the advantages of setting up a reusable base project, let’s have a brief overview on strategy and architecture. After working on a few apps (and assuming you are using basic good code practices like encapsulation, decouplingOO and SOLID principles), you will notice that you can simplify and abstract your application’s architecture to a diagram that (more or less) looks like this: Untitled drawing

Notice that this model should be considered as a very high level, generalised abstraction of how you could organise and group your classes. And indeed, we will use this as the base of the folder structure for our project. A brief explanation of this diagram can be found here. Based on the above diagram we can start exploring a reasonable file structure for laying out our code.

The goal here is to make a general purpose application file structure that will be reusable and intuitive for any team member or developer to use. The best approach to doing this is to set up all folders of your project using finder (or Terminal, if you’re hardcore like that). This will make sure that when you create classes for your project in the future those classes will be neatly separated in the file system as well as the project, like this →Screen Shot 2015-04-06 at 21.15.51

This will allow for easier porting across projects in the future. Think of these folders as groups of common classes that make sense in being grouped together. Later down the line you and your team will appreciate the thought put into the project order, as finding specific files will become second nature to everyone involved, no matter the size of the project. There is no rule of thumb on what the best file structure for a project is. As long as it follows some sense of order or agreed convention, in the end it boils down to personal preference. I suggest something like the following ( names in [] are [ folders ] ):

  •  [ Project ] ———————————– YOUR PROJECT
    • AppDelegate
    • [ Globals ] —————————- SUPPORT CLASSES
    • [ Factories ]
    • [ Extensions ]
    • [ Models ] —————————- MODEL LAYER
      • [ Protocols ]
      • [ Enums ]
      • [ Structs ]
      • [ Managers ]
      • [ Datasources ]
      • [ Networking ]
        • [ Requests ]
      • ModelObject1
      • ModelObject2
      • ModelObject3
    • [ Views ] —————————— VIEW LAYER
      • [ Cells ]
      • [ Components ]
      • View1
      • View2
      • View3
    • [ViewControllers ] —————— CONTROLLER LAYER
      • [ ChildViewControllers ]
      • [ Segues ]
      • ViewController1
      • ViewController2
      • ViewController3
    • [ Resources ] ————————- NON-CODE FILES
      • xcdatamodel
      • xcassets
      • [Plists ]
        • Info.plist
      • [Xibs ]
        • LaunchScreen.xib
        • Main.storyboard
      • [ Audio ]
      • [ Fonts ]
      • [ Localisation ]
      • [ Texts ]
      • [ Videos ]
      • [ Entitlements ]
  •  [ ThirdParty ] —————————— STUFF NOT DEVELOPED BY YOU
  •  [ Tests ] ————————————- YOUR TESTS
    • Test1
    • Test2
    • Test3
  •  [ Products ] ——————————— OUTPUT
    • App
    • Xctest

The benefit of a structure like the one above is that there is absolutely no confusion about where classes should be put into this project. All that’s left is to move this file structure into the project to replace the default Xcode one. You should now end up with a project structure that looks like this: Screen Shot 2015-04-06 at 21.12.26 This is already a huge improvement over the standard Xcode templates, and without doing any voodoo magic too! You can now start to pre-populate the project with your favourite utility classes and support files that you normally use and you’re almost set to go.

There’s a couple of abstractions that you could do to optimise the project renaming process. I suggest you abstract the root folder of your project (in finder) to something that is not your project name, a folder named “Project” or “Classes” will do. Note that when you do this you will have to redirect the root folder in the project, or re-import the folder. Also, rename your scheme of your project to something more generic and not project specific, like “Main”, “Development” or “Base”. You can do this by going to Product → Scheme → Edit Scheme.

Now got yourself a nicely ordered project that you can reuse at any time to kickstart future projects and save yourselves a couple of hours in the process. Nice.

Let’s give it a shot…

First of, save this project on your computer, repository or any other accessible location that works for you. If you are too lazy to follow instructions or you feel like you’re lagging behind, you can always just download our sample project, we’d be delighted if you spread the word! Now all you have to do is follow these simple steps when starting a new project:

  1. Copy the project folder to its new location and rename the folder to the name of your new project.
  2. Open the copied Xcode project.
  3. Double click on the project name in the left hand navigation pane, and rename the project, like so:Screen Shot 2015-04-06 at 21.48.09
  4. A pop-up dialog will appear on your Xcode telling you that it will rename all targets and tests. Make sure all items are selected and click on “Rename”:Screen Shot 2015-04-06 at 21.48.27
  5. Run the project…

And BOOM!!! Instant project template ready to deploy in less than 5 minutes. How EPIC is that?!

Up for a challenge?

Try to automate the lasts five steps using a script from the terminal and create an Automator application to run the script. (Solution to follow in my next blog post…) Pro Tip: Try and make the Automator application developer friendly, as you are trying to simplify your life, not add more complexity to it! You should show a pop-up asking users what the name of the new project will be and then keep it simple. Best of luck & until next time!

Author: Danny Bravo

Director @ EPIC