Universal Project Folder Structure
I have many projects. Some are research, some are code, some are physical DIYs, and some are pure documentation. Most projects start small but quickly grow into a mess, if I do not enforce a clean structure on them. What if we could organize most projects with a similar folder structure, such that it is easy for you and for others to navigate the folders and understand where each file belongs?
Here is my proposal for a folder structure that can be applied on almost all your file-based projects:
project-name/
│
├─ build/ the final generated product
├─ docs/ description of the product
├─ lib/ external dependencies maintained elsewhere
├─ make/ toolchain for making the product
│ ├─ config/
│ └─ tools/
├─ res/ static resources like images/audio
│ ├─ img/
│ │ └─ dia/
│ └─ css/
├─ src/ blueprint of the product, e.g. code
├─ test/ quality assurance of the product
├─ tmp/ ALL temporary generated files
│ ├─ objs/
│ └─ logs/
├─ xtra/ extra files not belonging elsewhere
├─ Makefile Trigger for setup/build/install
└─ README.md Information entry point
Features — Why should you use this?
- most important user folders (
build
,docs
) are sorted to the top. (you could also renamebuild
toapp
orbin
) - least important folders (
tmp
,extra
) are sorted to the bottom. - clear separation of dynamic files (
src
) and static files (res
,lib
) - clear separation of own code (
src
) and foreign code (lib
) - one folder for all temporary files with a descriptive name. Everyone will know that files in
tmp
can be deleted any time. - names reflect categories and not specific formats (e.g.
img
notjpg
/png
,make
notcmake
/waf
) - names start with a different letter which makes keyboard navigation fast (except for
tmp
) - names are short, which keeps overall path lengths short
- names are common and should be intuitive for most developers
Use Cases — Where can I apply this?
To get an idea how this folder structure can be applied in different scenarios, here are some use cases:
Compiled Program Code
This is the usal code repository, and could be, for example, a small game.
game/
├─ build/ the final game application
├─ docs/ compile instructions and a description of the game
├─ lib/ e.g. game engine modules
├─ make/ toolchain
├─ res/ static files like images/audio
│ ├─ models/
│ ├─ textures/
│ └─ sprites/
├─ src/ the source code in one or different languages
└─ tmp/ object files, log files
Written Report/Thesis/Paper
This could be standalone or the structure of e.g. docs/report
within a larger research project.
paper/
├─ build/ the final PDF, HTML
├─ docs/ notes (and maybe copies of literature pdfs)
├─ lib/ other LaTeX packages, text from ghostwriters :P
├─ res/ figures, diagrams, data for tables and plots
│ ├─ data/
│ └─ img/
├─ src/ LaTeX code, simulation code
└─ tmp/ temporary LaTeX files
HTML Website
If you use a static HTML generator, then the structure might already look familiar.
website/
├─ build/ the final HTML upload on your server
├─ docs/ notes about unfinished articles
├─ inc/ HTML templates, partials
├─ lib/ external CSS and JS files
│ ├─ bootstrap
│ └─ katex
├─ res/ own images, css, js
│ ├─ css/
│ └─ js/
└─ src/ Markdown files, SCSS files
Evaluation — Who is using this?
Exactly this entire structure is hardly found in any project. However, the individual folders with their purpose can be found at many popular software projects:
Alternatives — How can I modify this?
Maybe you think: “That’s not exactly what I was looking for.” Here some suggestions how you can adapt the structure to your needs.
Less Folders
To focus more on the high-level aspects of the project, you could try the following variation:
build/ the final product
doc/ documentation, manuals, plans
make/ things needed to build product
spec/ stuff from which the product is made
src/
inc/
lib/
res/ static resources
test/ quality assurance
analysis/
unit/
tmp/
Alternative Folder Names
Other suggestions for folder names that can be found in many projects.
│ Folder/Sub │ Alternatives │
│───────────────┼─────────────────────────│
│ build │ bin, app │
│ build/ports │ dist, platform, vendor │
│ docs │ doc, man │
│ lib │ deps, ext, modules │
│ make │ ci, devops, toolchain │
│ make/tools │ tools, utils, scripts │
│ src │ impl, spec │
│ src/modules │ addons, plugins, pgks │
│ res │ assets, media │
│ res/data │ data, db, │