Should your source code be in one folder or should it be nested?

January 25, 2010 — There are two ways to organize source code files for a project: flat or nested.

Here's a simple example of a flat structure(1 directory, 4 files):

📁myproject index.php theme.css helper_functions.php logo.png

Here's an example of a nested structure(4 directories, 4 files):

📁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:

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

📁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

📁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:

If you apply this algorithm to a sample project, you might get something like a project I just made with PHPUno

📁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:

In other words, the directory "icon" should never have a subdirectory in it.

📁myproject 📁images 📁icons

This means that any project should have at most 9 subdirectories.

View source