Project Organization starting on the right foot

Before I begin any project I like to take a step back and think about the project structure and basic foundation. This can be applicable to both existing and new projects. For an existing project you are just checking it to make sure that your foundation is good and will allow to grow in the future. For new projects its helps with setting the boundaries of what you need and how to organize it. So lets begin with the folder structure of a project

First this is a couple of folders that all projects should have:

-Project_Root
 |
 |-src
 |-configs
 |-dist
 |-docs
    |-reports
    |-api
    |-...
 |-lib (optional)
 |-bin (optional)
 |-packages (optional)
 |-node_modules (optional)
 |-tools

To start off the ‘src’ folder is where your source code will go whether its a webapp, C#, or something else all source code and project files should exist in here

The ‘configs’ folder is where you should put configuration files. These files are configure your projects building, deployment, etc

The ‘dist’ folder is where you should build all files to. So when compiling and building the source code it should dump its output to the dist folder. Some projects by default go to src/project_name/bin/debug/stuff. I think its better to have your projects output to dist so change your output path to something like this ../../dist/debug/project_name/stuff

The ‘docs’ folder is where you put all your documentation about the project your working on. It should be full of various markdown and folders detailing all the stuff in your documentation. There is at least two sub folders called api and reports. The api folder is for storing the details about the public api of your project. The reports folder is for storing test reports and other reports about what the project and its build development history.

The ‘lib’ folder is a folder of third party libraries that can not be linked using package management. If using package management like NuGet you will use the ‘packages’ folder. If you use npm then of course you will want to use node_modules.

The ‘bin’ folder is for third party executables that will be packaged with your project in the dist folder.

The final folder ‘tools’ is for third party executables that will be used in the build process or some other development process but will not be part of the packaged software.

Now you need some basic files like these:

• README.md
• CHANGELOG.md
• LICENSE
• build.(bat, sh, ps1, cmd)

The README file is where you would want to all details of your project. Things like the description of your project, how to build it, how to contribute. You may also want to link to your license, changelog, statuses from CI as well.

The CHANGELOG file is where you put all changes that occur for particular releases of your software.

The LICENSE file is where you put the license for your project

The final file in the root of your project is the build script. This file should build your project and output to the dist folder. It should not rely on anything beyond whats in your project. In my experience I usually use a build process like cake as my build script. I will go into that in more depth in a future article.

This project structure will allow you to start a good and clean project. The folders will allow you to organize your files in a logical fashion that support your project going forward. Thats about all you need to get started on the foundation of your project. Next time we will talk about documentation and how to automate it.