Project structure documents project organization. Unfortunately its an oft neglected source of information. Its easy to think that important work only happens to the right of the file tree, but a shoddy file structure means a lost opportunity to communicate something about your work.

Most projects start (and unfortunately end) as some version of this:

| lib/
| ---- model/
| ---- service/
| ---- io/

Only one thing is clear after looking at this file structure: You have no idea what this project is about. It could be about medical devices, an ecommerce site for socks -- whatever. It tells you nothing about business logic.

The problem is that this structure is implementation focused. And the reason its popular is because implementation-focused project structures are easier to use. As a tool, the above project structure fits well with the way developers operate. The core domains of implementation are usually constant while business logic is comparatively fluid. Every project relies on models and services, so why not just package them together so they can weather last minute changes, feature creep, and any surprise the product team throws its way?

But project structure should not be a tool. It should not sacrifice communication for ease of use. Its meant to be informative. And that starts by being easy to read.

Project structure should communicate an idea about how business entities interact.

Take a look at this structure:

| lib/
| ---- authentication/
| ---- login/
| ---- inventory/
| ---- delivery/
| ---- billing/
| ---- user/
| ---- common/

A programmer should be able to look at a project structure and discover not only the individual pieces of the project, but also some information as to how they interact. From this structure one can make a few insights:

  • Its a user facing application
  • Users must create accounts and authenticate
  • There is an e-commerce arm with an inventory of products

Each sub-directory is focused on business domains. At a glance you know something about how the application works. Once this idea has been documented, then the implementation details factor in:

| lib/
| ---- authentication/
| ---- login/
| ---- inventory/
| -------- models/
| -------- services/
| -------- data/

It requires a bit more planning, but the reward is a project that is self explanatory. To paraphrase this guy, any time spent commenting, or in this scenario explaining implementation, is duplicate work. If the basics of how your business entities work together are not self-evident, your project structure probably needs to be rewritten.

If you decide to walk this path, what you end up with is a file structure that is pleasing both to the eyes and to new faces on your team. Your project is a valuable source of documentation in itself. Don't squander it.