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
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
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
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.
Related topics/notes of interest
- Xcodeproj - a Ruby utility that allows you to edit and interact with the Xcode projects via the command-line.
There is no easy way to rename a directory after adding it to the Xcode project. You will need to edit the
.pbxprojfile directly. What I did is close Xcode, rename the directory on the terminal (or Finder) and then find the
.pbxprojfile inside the Xcode project and search and replace all the references to the old name with the new directory name.
When you move your files arround, you might put your
Info.plistin a different location than the one Xcode is expecting. Remember to change the
Info.plistpath on the