-
-
Notifications
You must be signed in to change notification settings - Fork 3
/
should-your-source-code-be-in-one-folder-or-should-it-be-nested.scroll
170 lines (118 loc) · 5.67 KB
/
should-your-source-code-be-in-one-folder-or-should-it-be-nested.scroll
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
date 2010-1-25
tags index
permalink should-your-source-code-be-in-one-folder-or-should-it-be-nested.html
title Should your source code be in one folder or should it be nested?
pageHeader.scroll
There are two ways to organize source code files for a project: flat or nested.
Here's a simple example of a <b>flat</b> structure(1 directory, 4 files):
code
📁myproject
index.php
theme.css
helper_functions.php
logo.png
Here's an example of a <b>nested</b> structure(4 directories, 4 files):
code
📁myproject
index.php
📁styles
theme.css
📁images
logo.png
📁 helpers
helper_functions.php
Both of these structures can accomplish the same thing. Which is better?
If you've worked with me on any project before, you'll know I prefer flatter structures. I try to resist adding directories as much as possible (you always have to add them eventually, but I like to fight it to minimize this effect).
I don't know why my gut tells me to minimize directories, so I thought I'd write about it and see if any rationale emerged.
# Benefits of a Flat Structure
# Benefit #1 - Quicker access to files
I primarily edit files using Notepad++ on Windows 7 or vim. If you keep all your files in 1 directory, you can open them faster ("Control+O", type a few letters on Win 7, or just "vim filename"). So, a flat structure gives you quicker access to files. I've never timed this before, but am pretty positive it works.
# Benefit #2 - Avoid file path issues
Dealing with paths when working with a website is often the cause of careless bugs. If everything is in one directory, it makes it painless to include things on both the server side(include 'file.php';) and the client side ('src="script.hs"'). Once you start nesting directories, it's easy to make mistakes.
# Benefit #3 - Easier to bring people up to speed
When I join an in-progress project or use a new library, I like to try and wrap my head around the whole thing. I can't do that if I have to dig into different directories to see all the files. Why hide 50% of the project in subdirectories?
# Benefit #4 - Avoid overwriting issues
Occasionally you'll have a structure like this:
code
index.php
📁admin
index.php
You might accidentally overwrite one index with the other, or edit one index when you think you're editing the other. Doesn't happen too often, but occasionally it can be annoying. By sticking everything in one directory, you don't run into that problem as much.
# Benefits of a Nested Structure
Of course there are benefits to having multiple directories, otherwise this style wouldn't be so popular.
# Benefit #1 - Looks more organized
It's nice and neat to have your files tucked away into nicely labeled directories.
# Benefit #2 - Easier for teams
It can be easier to divide work between team members when things are in different directories. For instance, why should the designers need their images mixed in with backend files?
# Benefit #3 - A directory with too many files becomes unwieldy
I'll admit, once you have more than some threshold of files in a directory, it can quickly become hard to manage. If the files are nearly all of the same type (say, php files), then it's not as bad. But once you have 20 php files, 3 javascript files, 15 images, 4 css files, 2 bash files, 3 readmes, and 45 text files, it might be time to split things up.
# My theory on why directories are bad.
Less paths create an easier mental model.
If you walk into a messy room, it can be hard to create a mental model of the contents of that room. This is the equivalent to a file structure like the one below:
# Bad
code
📁myproject
a_image.png
base_functions.php
dog.js
index.php
mike.png
names.csv
new_logo.jpg
test.php
xmlfunctions.php
zlib.js
It's a mess.
If you walk into a room where everything is put away(clothes in the dresser, books on a bookshelf, odds and ends in the drawers) it's easier and an improvement. A room organized like this looks like the file structure below:
# Ok
code
📁myproject
index.php
📁images
a_image.png
mike.png
new_logo.jpg
📁php
base_functions.php
test.php
xmlfunctions.php
📁scripts
dog.js
zlib.js
📁data
names.csv
But now you've introduced the problem that to access nearly anything, you have to "open a drawer". You also can't see everything all at once.
# Best
The optimal solution is to not put your stuff into drawers, but to:
- 1. Remove as much stuff as possible.
- 2. Put the remaining stuff out in the open in neats piles in separate parts of the room.
- 3. If, and only if, you have a ton of the same type of thing, put those into their own drawer/cabinet.
If you apply this algorithm to a sample project, you might get something like a project I just made with <a href="http://github.com/breck7/uno">PHPUno</a>
code
📁dropdate
📁data
1
2
..
578
index.php
logo.png
sprites.png
style.css
uno_controller.php
uno_app.php
uno_models.php
uno_helpers.php
# Search, don't sort
Gmail has an adage "search, don't sort". I think it applies here. Directories are a form of sorting, while autocomplete(which is integrated into practically everything nowadays) is a form of searching. By sticking everything into one directory, you enable search. Create multiple directories, and you disable search.
# The Rule of Three
Here's a simple rule of thumb to help you organize your folder structure better:
- No folder in your project should have more than 3 subfolders.
- There should not be more than 3 levels in any project.
In other words, the directory "icon" should never have a subdirectory in it.
code
📁myproject
📁images
📁icons
This means that any project should have at most 9 subdirectories.
footer.scroll