I've looked into many open source software repositories, and I've found some common elements and somethings people do in different fashion from one another.

For example, every repository has a README file, a INSTALL file, a COPYING file and stuff like that.

Other things differ:

  • Some projects, like git, have their source code in the root level, while others have the source code in a src/ folder and others, like the Linux kernel, have the source code spread in different folders in root level, that divide code by areas;
  • Some have their tests in a t/ folder, while others in a tests/ folder, or named otherwise;
  • Some have files about submitting patches and who the maintainers are, and those might be inside some Documentation/ or in the root level.

Are there recommendations? A best practice?

For example: personally, I don't like the code in the root level, git-fashion. It looks messy and confuses one trying to start as a contributor (especially because they have some code inside folders, and scripts in the root level as well, it's really messy).

If I were to start a project of my own and wanted to start right from the start, are there recommendations? Best practices? How can I make a clean and clear structure?

  • 6
    Some languages or build tools have specific conventions. Aside from that, this question boils down to personal preferences. There is no “right” answer. – amon Oct 16 '17 at 13:05

Reserve your root for misc bits (so you have a place for misc related directories and files which may be valuable to store in your repository), start your source tree one level down. To accommodate a place for multiple components perhaps add a second level for your first component.

If your are using git you can always reshape later, don't worry about it too much.


This question was asked a really long time ago, but saying as you didn't mark a solution, I think I'll add a contribution.

Basing of my experience with open source, you should consider a few things before setting up structure.

Things to consider

  1. Language and Technology: Frameworks and languages dictate a lot of what your structure should look like. For example, web development structure with PHP will look different to C++ desktop

  2. Deployment: If you need to deploy this code in this raw form (so a program in python for example), your structure will look a lot different to a compiled program. The Python structure will actually be visible to the end user, therefore influencing how it should look.

  3. Frameworks and includes: If you are using any third-party libraries in your project, your structure will most likely need to be adjusted.

  4. Source Control: Which source control provider you are using may affect where certain files are placed.

However, despite all this, you can generalise most structures down to the following.

Stock Structure

  1. The Root: The root should be reserved for configuration files, documentation (such as README.md and others). Also, it can contain VS solution files and git files.
  2. /src: We all know this one. This is where all source files are placed. However, in languages that use headers (or if you have a framework for your application) don't put those files in here.
  3. /lib, /dep, /inc etc.: This is the directory where all your dependencies should be stored. Also, if you have your project in multiple files, put your headers and attached source in here.
  4. /doc: Documentation goes in here. For example, docs.md.
  5. /res: A less common one. For all static resources in your project. For example, images and audio.
  6. /tools, /scripts: Convenience directory for your use. Should contain scripts to automate tasks in the project, for example, build scripts, rename scripts. Usually contains .sh, .cmd files for example.
  7. /build: The place where your built files will go. Usually split into two directories, Debug and Release, it can contain binaries, .DLLs and any compiled files. It may also contain build scripts, like makefiles, but they should generally be in the root.
  8. /test: Contains unit tests... no, in fact, all tests!

Notable Examples

I've found a few nice examples of good structure for you:

Both of these projects are large, open source projects which have a very well defined structure.

I hope this helped you.


If your repository is a library that you expect to distribute or deploy as a package, a specific structure may be necessary. For instance, pip has some strict rules about different files and their locations, which would translate into a specific structure of your repository.

A framework could also dictate some of the rules.

Tools that you use may also have specific expectations. For instance, for projects created with Visual Studio, you'll find an .sln file in the root directory, and the virtual structure of the solution in Visual Studio won't necessarily reflect the physical structure of the files. For instance, the projects may be grouped together in the virtual structure of the IDE, but be all stored in the root directory on disk.

Your community may also have a specific style. For instance, it is not unusual for C# projects to be grouped as this:

  • /Project1
  • /Project1Tests
  • /Project2
  • /Project2Tests

instead of having an /src and a /tests directory. It seems that you've been using a language where /t is common; I have never seen any repository which has a /t directory in it.

Finally, the tools around version control may also have their constraints. For instance, if you use GitHub, having a README.md would be a good idea, because GitHub will automatically display the documentation inside this file.

Once you collected the rules of:

  • The package manager,
  • The framework,
  • The IDE,
  • The community,
  • The version control ecosystem,

you should have a clear vision of the rules to apply. In doubt, check the open source repositories for your language/technology of choice, and copy their structure.


If your project is meant to be open source and it's addressed to the community, whether you like them or not, it's good to follow the "standards" or common practices adopted by the community for your specific stack.

Even if it's not OS, it's good to adopt them, especially if someone else has to work on it.

If you dislike the way the community organise code, ignoring this and going your way could make possible collaborators to feel uncomfortable and don't adopt your project. Some things are assumed as "standard" by many. For one reason or another, the community adopt some practices and assume they are going to be this way by default. That encourage 3rd parties to implement tools that take these practices as "defacto standards" and build their functionalities upon them. Think about how Maven imposed the basic project structure in Java projects. Or how SCMs as Git has encouraged the use of markdown files like README.md or CHANGELOG.md in the root. The think about those plugins for Jenkins that look for java binaries in target/classes after the build.

As @Amon commented, in the end, it's up to you to agree with these practices and follow them. Just bear in mind that ignoring them could make your job unnecessarily complicated. For example, by having to twist the IDE configurations or setting up uncommon env vars just because nothing is where it's expected to be by default. I would not expect too much support form the community when things go wrong either.

Q: Best practices?

I encourage you to adopt the concrete practices and conventions of the community for your technological stack. It will make easier for you to find support when need it and probably it will ease the instrumentalization of the SDLC through tools that assume you are following the conventions.

Q: How can I make a clean and clear structure?

Directory tree aside, there are some well-known strategies to organize the source code. These are related to the packages|namespaces (for some languages this is tightly coupled to the directory tree too). I'm speaking about the package by feature, package by component or package by layer. From the development (and developer) standpoint, these are more valuable when it comes to clean code. Definitively, we developers don't' navigate through folders. We rather navigate through namespaces or packages (most of the time I mean).

From an architectural standpoint, one rule is keeping unrelated things separated. The more unrelated the more separated, from different folders to different projects and hence different repositories.

From the SCM standpoint. Well, Github, Gitlab, Bitbucket have lookups and browser to look for files and contents from the web console.

Not the answer you're looking for? Browse other questions tagged or ask your own question.