Before we begin I'd like to ask you a question- when you are about to go on a trip, how do you pack your suitcase? Do you separate the shirts from the pants? Do you use some sort of organizers for your clothes or you just fold everything into one big pile?
The reason I'm asking you this is because a few months ago, during a code review session, my teammates and I argued about how we should separate a certain logic between the files in the project. We argued about it for some time until Guy, one of teammates, stood up and asked me: "When you pack a suitcase for a trip, do you put your swimsuit along with your undergarments or inside a separate bag?" my answer was immediate - a separate bag of course - but just like in a Disney movie Guy's question took me 9 years back in time when my family and I had a family trip to Eilat and I had to share a suitcase with my older brother. Back then I wasn't as sophisticated as I am today with my dedicated organizers and I did not know how to keep the suitcase organized throughout the trip. I remember how quickly everything in the suitcase got messed up and how after two days(!!!) I found myself re-inventing new rules for the suitcase organization's sake.
Recently, I got to plan the file structures of several projects - one of them was our frontend project and the rest were our backend services. These golden opportunities gave me a chance to research and understand what is, in my opinion, the right way of organizing a project's file structure.
In this article, I'd like to share with you why I think that your project files structure is one of the most important parts of your projects and my personal guidelines on how to build a files structure that I believe can improve the efficiency of the code and eventually lead to a healthier and faster development cycle. 🧘🏼♀️
Why
The main reason I love planning files structures is that it's like putting my application under the microscope, it enforces me to know which parts of the code can be grouped and which parts can work as independent units, what is stateless, what are the data flows and last but not least, what is my domain. It is almost like running my application through an MRI scan 😅 and knowing the answers to these questions significantly affected my understanding of the project and the application.
I believe that establishing a proper file structure is just like embracing code style and design patterns - it can clarify the dependencies and responsibilities of each file and part of the code and make the code more clear and efficient. From my experience, an organized file structure enables quick entry for new developers to the project and an optimal environment for fast development and delivery speed.
How to Organize File structure
The 3 goals
When I think about the ultimate file structure I imagine a structure which consists these 3 main goals:
Easy to maintain
Easy to file and easy to find
The ultimate way to test how "good" your file structure is to check how long it takes(for newbies👶🏼 and seniors👴🏼) to find a particular file in the project - the less it takes the more efficient it is. Keep in mind that file structure becomes powerful when there's no need to remember anything, ideally, it just needs to make sense so that unconsciously we know where every file is or where it belongs.
Reflects the application
Correct file structure tells the story of the application
I believe that every application has a story to tell, what its domain is, which features it holds, what layers it contains and what are the interactions between them, use the files structure like it was the index of that story's book - try to specify the logical structure of the data and the relationships between the application's components. This can help to define the data flows more clearly and especially needed when collaborating with others. 🤝
Make the best sense for the team
The one that would make the best sense for the teams is the best solution.
Whether you are working in squads or teams, guild or chapters, conformant the file structure with your organization improves the scalability of the application, especially in smaller companies. One key reason for that is that as your company grows you want to expand and grow easily while continue to move fast and deliver, for that you need to maintain the application flexible and more adapted to organizational changes. For example, a company that works with squads might separate the application's project by features, on the other hand, a company with developers working on different technologies(front-end and back-end developers) organizing the projects by type which is easier to classify, back up, and migrate might be more suitable.
However, knowing what to aim for wasn't enough, I still needed some guidelines and standards so I decided to try analyzing what exactly guides me during the process of planning a file structure.
The 5c's - 5 key principles for a proper structure
For a few months, while working on the file structure of several projects, I tried to figure out what is actually the thought process I do to build the structure for a project. I wrote down all my thoughts and concerns, the questions I asked and the answers I got until I finally came out with these 5 key principles:
👓 Clear
Think about your files and folders' names, keep it short(less than 25 characters) unique and meaningful so that the next developer will intuitively understand what are the responsibilities of that file and what it contains. I recommend to think about the file's names as keywords, based on their folder names. For example, inside folder called services I would expect to see userService and not user. Moreover, if I read a file with the name userService I would ultimately guess it's inside services folder.
This will save you a lot of time when you need to modify your files or navigate in your file structure.
🐾 Consistent
Choose a naming convention and follow them consistently, this will automate your workflows and save you time by keeping your code organized and understandable.
Examples:
• Angular: {fileName}.{type:component|service|test…}.{format:ts|css…}
• Go: files and folders names should camleCase based on what they are or what they do and {fileName_test}.go for test files.
• React: UI components should be PascalCase and {ComponentName}.test for test files.
• Java/C#: each file name should consist of the case-sensitive name of the top-level class it contains, plus the .java extension.
🌼 This is the pattern that I use for most of the projects:
I like to think that I took the best from every technology 😊
💎 Concise
Avoid overlapping and don't let your structure get too deep, it makes it harder to write relative imports or move files between places but mostly takes out the grouping context from a grouped files. A rule of thumb that I personally use - when your structure's nesting exceeds 3 levels you are probably gone too deep buddy 😏
✔️ Correct
Group all files and place them in your structure as they exist.
Let's break this down:
(i) "…group all files" - it can be by feature or by type of layer(such as service, controller, component, or stand-alone-scripts)- feel free to choose whatever works the best for you but follow it on the entire project.
Personally, in most cases and especially in front-end projects, I prefer to group the files by feature so that every feature-folder is an independent unit like a lego brick. One key reason for that is that I believe that people work on features and not on types of files, when I close my eyes and imagine my application I think about its views and the features it holds. The second reason is that I was surprised to find out how to modularize the project by features encourage everyone on the team to think about modeling the entities, the layers, inverting dependencies, decoupling code, and define flows in the application. 😌
Here is an example of a React project where the items are
grouped by feature:
dashboard and marketplace folders are both features in the application and each one contains its required internal items such as components, services, routes, etc.
For further reading about folder-by-feature, I recommend reading Tim G. Thomas's article.
(ii) "…place them in your structure as they exist " -
Use your file structure to reflect the architectural relationship between the components(features, types, etc…).
When I'm about to place items in the project I try to find which feature or layer in the architecture this component belongs to, what its scope, is there any architecture restrictions from or of that item?
Let's take for example the following snippet from a simple backend Node.js project:
As you can see in this project the items are group by type and the code is separated into 3 architectural layers: services, stores, and controllers. To reflect the architecture-relationship between the layers, I placed someEntityModel inside its own parent - someEntity- store folder because someEntityStore is the only one who deals with someEntity 's logic, placing it outside of this folder might imply that another store can import it and I didn't want that. On the other hand, all the stores can import db.ts, therefore it should be placed in the store's folder as a sibling to all the stores.
Now, you probably think that making sure you placed a file in the right place can be sometimes very confusing. A rule of thumb that I personally use is to ask myself "Which files can import it?" if my answer is either parent of the file/sibling of the file/I placed it in a dedicated well organized shared folder everything is ok, my file structure is aligned, everything is in its right place and I can keep on rocking it 🤓🤟🏻
💼 Conformant to the company workflows
Develop a folder structure that makes the most sense for your project or team, the best folder structure is the one that mimics the way you think.
🌸 Summary
I started my journey in the beloved arms of .NET framework and Angular, over the years I switched to React, Java, Node.js even Go. If you ask me, you can't take the framework out of a developer, you can leverage it 😌 and maybe the lack of "strict structure" is what made me so passionate about finding guidelines and standards in the first place.
This research gave me a lot of knowledge about the importance of file structure, how to structure and develop applications but mainly it showed me that I shouldn't look for "The One", there isn't one structure to rule them all like there's no one way to backpack your suitcase.
Finding the right file structure is like choosing and backpacking your bag, the one that would make the best sense is the best solution.
I hope my experience will inspire you to explore your projects and who knows maybe to find new ways of backpacking a suitcase 🙌🏻.
Special thanks to Guy Warburg and the rest of my teammates at datreeio.
Top comments (6)
Thanks, I found really useful and I'll try to follow your advices, I'm programming student but I think it's really important to planificate a good structure before programming then you have not to deal with some problems or even find good names and also the people that will code afterwards will be easier to understand the functionality of that code.
Thank you Jordi, I couldn't agree more 😊
You're welcome Noaa, as a student and interested in keeping learning an improve about things it's a gift to find posts like yours and I hope we can help us in this code journey. :D
File structure tends to become only a problem in a project when the project scales. When the problem shows up, it is usually too late to easily fix it.
I stumbled across an npm package (destiny) that allows to automate this process based on a fractal graph model (read more here).
Very interesting, thank you for sharing :)
I totally agree but IMHO itד is worth "wasting" time on standards even when the product is still in its diapers
I faced the struggling of building apps without solid standard of file structures or naming and I must say it made me work more with more struggles.
Thanks for the article, it really helped me to realize how much planificate a good structure is useful and gave me some principles to talk about with me team :)