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 rename build to app or bin)
• 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 not jpg/png, make not cmake/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:

• Go: doc, lib, src, test
• jQuery: build, src, test
• Rust: library, src
• Electron: build, docs, lib, spec
• Protobuf: docs, src, cmake, toolchain
• Pandoc: app, data, doc, src, test

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,               │