OdeToCode IC Logo

.NET Core Opinion #3 - Other Folders To Include in the Source Repository

Thursday, September 13, 2018

In addition to src and test folders, there are a few other top level folders I like to see in a repository for a .NET Core code base.

benchmarks – for performance sensitive projects. Benchmarks typically require a benchmarking framework and perhaps some custom applications. All of the benchmark related code can live inside this folder.

build – for build scripts and other build related files. Some build systems require build artifacts to live in the root of the repository, but supporting files can live here to avoid cluttering the root. More on build files in a future post.

docs – for markdown files, diagrams, and other documentation. There are a few possible audiences for this folder, depending on the project type. For OSS libraries, documentation could include contributor focused documentation, like build instructions and style guidelines. For business apps, the folder might target users with setup instructions.

samples – for code to demonstrate libraries and frameworks. My basic rule of thumb is that if the repo builds NuGet packages for other developers to consume, you’ll want a samples folder demonstrating some basic scenarios on how to use the package.

scripts – for scripts related to the project. These could be automation scripts for sample data, computer setup, cloud provisioning, or desired state configuration. More on scripts in a future post.

specs – for those projects building on published specs. Examples would be HL7 specifications for a health data parser, or the open language grammar for a parser.

tools – for utilities, possibly from a third part, that are required to build, run, or deploy the code.

As an aside, many of the benefits of .NET Core being open source are not related to the source itself, because we’ve always been able to get to the source code with tools like Reflector. Many of the benefits are seeing other artifacts like unit tests, sample projects, and experiments. When I was learning .NET Core, I found these other folders invaluable.

Coming up: more on the build and scripts folders.

Gravatar Stephen Brouillard Monday, September 17, 2018
Nice! This may be a quick-hit post, but it does give some food for thought about what else to include and how to organize it.
Gravatar Jacob Stamm Tuesday, September 18, 2018
Looking forward to seeing more info on build and scripts folders. Regarding the specs folder, is it possible that this could be an ambiguous name choice due to testing frameworks like Jasmine being made up of specs?
Gravatar scott Tuesday, September 18, 2018
@Jacob: yes, I've worried about the confusion.
Your Comment