The Best Way to Organize your iOS Project Files in Xcode

C is for Creative Mess

If you use standard Xcode Groups to organize your files in project — you will eventually find out that it creates mess in your project root folder on a disk. Xcode Groups (folders) exist only virtually, while on the disk you will see plain list of created files in the root directory, and that can potentially lead to some possible uncomfortable situations and even risks.

Note: I’m using classic MVC architecture in all examples to provide all level access to these tips. I’m sure the same principles you can apply to MVVM, VIPER and other approaches.

First of all why you should care?

Imagine you return to your 2-years-old project to fix something. Or even somebody’s old project? And you just can’t understand the project’s structure by looking into files structure because all files are mixed. What if project file is corrupted and whole virtual Xcode Groups structure is gone? You know that you need to fix something in Profile controller, but where will you start looking for it and related classes? That can potentially consume a lot of time for you to make any changes in the project, especially if you working with multiple projects at time. Here is how it looks by default when you use Xcode groups:

Files Structure on Disk and in Xcode Project

Git also doesn’t support this approach either because it can only work with files structure on the disk, and you can’t add specific folder to commit or use other good features.

What should you do then?

It’s a little bit hard to get used to it, but you can develop the skill that will help you to do it all the time. The algorithm is simple:

1. Right click on folder where you want to create new “Group” -> and select “Show in Finder”

1. Use Show in Finder option to quickly navigate to any folder on the disk

2. Create new folder you want:

2. Create folder on the disk

3. Drag’n’Drop your newly created folder into Xcode:

3. Drag’n’Drop your newly created folder into Xcode project

4. Do not forget to select Create Groups instead of Folders References, and unselect Copy items if needed option, like here:

4. Add Folder Options: Select “Create Groups” and unselect “Copy items if needed”

5. From now on, you can create files inside this folder and they will automatically appear in your created folder:

5. Newly created files will follow your project structure

That’s it. When I was only starting to work with files this way, it was a little hard to get used to it. But now I’m doing this on auto-pilot and it saves a lot of time when you searching for something, or trying to fix something in the project. Also it even improves GitHub web interface experience, especially when you work with PullRequests in your team.

The Better Way to Organize Files in Project

So now we can finally get to Project’s File Structure. There are many ways to do it and Apple doesn’t tell us what is the best one. It also depends on what you are using in your project: Storyboards or Nibs, static data (plists, json) or dynamic data from server and so on.

The most popular approach I think is to separate files into big groups: Views , Controllers , Models , etc. And sometimes repeat the structure inside:

Popular Approach is to organize your files into big groups

But this structure is very specific and not flexible at all.

So what I found the best for me, and what usually works for my projects is organize everything around UIViewController , by keeping all the related files in the same folder:

Example of how I usually organize the files in Xcode project

As you see in this case all the controller-related files are stored near controller, so it’s much easy to find and add/modify/remove them. While common files that used across the different controllers should be moved to root Views/ folder for example. Also it’s very handy if you store your local data in plist or JSON file instead of code.

Thanks for reading! I hope you find it useful or at least it gives you some fresh ideas. Tried to keep it short, but if you want some more particular examples and/or have suggestions — Please let me know in comments below!