Xcode code structure - matching groups and filesystem May 24 2019

A folder structure makes it easy to navigate and understand any project. On Xcode, we can build the project structure using groups. The problem with this is that it doesn't reflect on the filesystem. What this means is that if we are looking at the code on the filesystem, or on Github, we won't have the benefit of the project structure. In this post, I'll explain how to share the project structure on the filesystem and on Xcode.

Xcode groups don't reflect the filesystem by default
General project structure
What about cases that don't fit that structure?
Additional thoughts for larger projects
Final thoughts
Related topics/notes of interest

Xcode groups don't reflect the filesystem by default

If you create your structure using groups on Xcode and then check your filesystem, you'll see that all the files are clustered together on the root directory. To make the groups match the filesystem, you should create the directories first and then add them to Xcode to build the connection.

Let's create the Controllers directory, you can do it using Finder or the Terminal. I'll explain using the Terminal:

1
2
$ mkdir Controllers
$ open .

The last command (which must include the dot) will open the Finder on the current directory so we can drag and drop it to our project in Xcode. You will see a window popup, make sure the checkbox is not active for Destination [ ] Copy Items if needed, and Added folders is selected as Create groups.

Adding folder to Xcode Project Screenshot

Once you have the group Controllers created on your project, every file you move to that group will be reflected on the filesystem.

General project structure

The project structure should be tied up to the architectural pattern, for example, if we use an MVC pattern, we can create the following folder structure:

1
2
3
4
project/
├── Controllers
├── Models
└── Views

This way, it will be clear where to start searching for any file on the project. This example is simplistic, there would be files that will be hard to place under this structure, for example, where to locate Protocols or Extensions?

I will suggest starting with the following basic structure:

1
2
3
4
5
6
7
8
project/
├── Controllers
├── Models
├── Views
├── Library
├── Protocols
├── Extensions
└── Resources

Most of the folders are self-explanatory, the only odd one would be Resources, in that folder I would add images, storyboards etc.

What about cases that don't fit that structure?

The sample structure is only to get you started. If you need a specific group for anything not mentioned, create it, be flexible but try to keep it simple. If for example, your project has many storyboards and it doesn't make sense to keep them in Resources, then create a new directory called Storyboards and add your storyboards there.

Additional thoughts for larger projects

When you have a sizable project that contains several models and controllers, and it is proving difficult to find files, I would suggest splitting the project structure by features. As proposed by John Sundell. You can end up with a structure like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
project/
├── MultiUser
│   ├── Controllers
│   ├── Models
│   └── Views
├── SingleUser
│   ├── Controllers
│   ├── Models
│   └── Views
├── Network
│   ├── Controllers
│   ├── Models
│   └── Views
└── UserPreferences
    ├── Controllers
    ├── Models
    └── Views

Final thoughts

It is vital to have a good structure on your project, this will help you make your projects easy to understand by other programmers and by yourself when you come back to read the code after some time.

You might think that you don't need to do the extra work of having the structure match the filesystem because you only use Xcode but if you are using Git to keep track of your projects (which you should), anyone that checkouts the repository will thank you for the additional information the structure provides.