Types of Layouts
The layout of a project depends on its type and purpose. The layout should suit the project well to help supporting it.
A good way to describe the importance of using a good layout is an analogy with clothes. We all have things that suit us well; in this case the clothes fit us naturally so we don't even notice its presence. When a thing doesn't suit well, we might not notice it too, but by the middle of a day we've experienced more stress; when the garment is taken off at the end of a day, it feels much better.
The same is true for a project. Its structure may be unnoticed because it's natural and convenient, whereas with other projects we sometimes can't recognise the source of anxiety. That anxiety, in fact, is a sum of many factors, and one of them might be an inconvenient structure of a project.
A project is created once, and is maintained until its end of life. This means that you really want to invest in a good structure so interactions with codebase are on the positive side, and facilitate productivity.
All projects are different, and there is no a hard set of rules one can follow without thinking about a particular use case. Yet we can confidently say that the majority of projects fall into one of the following three categories:
- libraries (packages, modules, frameworks, you name it, depending on the language and environment)
- single services/applications (web services, CLI tools, GUI applications, etc)
- all-in-one, or monolithic repositories (multiple services/applications and libraries).
Some recommendations for different types of projects can be applied to all of them, and some are specific to a particular use case. For example, a library layout will be slightly different from a monolithic one.
By a project we mean a few related and similar things at the same time:
- the directory containing a project
- the repository containing a project.
In the modern world it's hard to imagine a project that is not published on some service for collaboration and synchronisation with other people. Even if a developer is working on a project alone, they still need to keep it in sync between different devices, and to make sure the code is not lost, if something happens to a computer.
Given that, the section assumes that some service is used to store code of a project. While there are many of them, for simplicity we assume it's GitHub.
The rest of the section focuses on describing guidelines; we start with the commonalities, and then consider aspects that are different. Because it's not hard rules, but rather suggestions, they're flexible, and will differ from project to project. There are also some exceptions, which is natural for any healthy-sense driven guidelines.
Disclaimer: Neither the author, nor this work are affiliated or benefit in any way from GitHub.