12

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?

2
16

Based on my experience with open source, you should consider a few things before setting up a structure:

Things to consider

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

Deployment: If you need to deploy this code in raw form (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.

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

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

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.

/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.

/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.

/doc: Documentation goes in here. For example, docs.md.

/res: A less common one. For all static resources in your project. For example, images and audio.

/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.

/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.

/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.

6

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.

0

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.

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