How to organize a Visual Studio Solution

Visual Studio is a capricious product, and its "Solution" subsystem is especially capricious. When you look at what options are available you might think you have a great degree of freedom to structure things the way you want, but as you will inevitably (and painfully) find out later, many things have to be done in precisely one, entirely undocumented way, or else there will be pain of the worst kind: Visual Studio will malfunction either without any error message, or with error messages that are completely unhelpful for locating and fixing the problem.

Here is a list of things I have (painfully) found out over the years.

(Useful pre-reading: About these papers)

The project directory structure must be entirely flat.

All project files must reside in directories that are immediate sub-directories of the solution directory. When adding a project you are given the freedom to put it in a directory anywhere you want, but if you don't put it in a directory exactly under the solution directory, you are going to run into trouble later.

If you have hundreds of projects, and you are thinking that putting them all in one directory is insane, welcome to the Microsoft world, where insane is the order of the day.

From within Visual Studio, you can create what Microsoft calls "Solution Folders" to arrange your projects in a hierarchy at least within Visual Studio's "Solution Explorer" panel, but even this has a caveat, keep reading.

The startup project must be listed first in the solution file.

The solution file is a text file in a ridiculous ad-hoc format which consists of, among other things, entries delimited with "Project" and "EndProject". You are free to edit this text file and re-order these entries in any way you like, and it seems to have absolutely no effect because the Visual Studio Solution Explorer will sort them alphabetically anyway, but there is one kind of re-ordering that you can do which actually matters: The entry which stands for your startup project must be the first entry.

If you do not do this, then each time you delete the .vs directory, restart Visual Studio, and try to launch your solution, you will be greeted with the all too familiar, extremely annoying, and extremely stupid message which says that you cannot launch a project which builds a library instead of an executable. This is happening because when the .vs directory is deleted, Visual Studio forgets the startup project, and when Visual Studio is launched with no startup project configured it absolutely has to establish a startup project, and it absolutely has to do this automatically, without asking you. In doing so, it picks the first project that it finds in the solution file, and it is not smart enough to skip projects that build libraries instead of executables.

The startup project must not be nested in a solution folder.

As mentioned earlier, you can use "Solution Folders" to arrange your projects in a hierarchy; however, the project that you usually want to have as the startup project must not be nested in a solution folder, it must be placed right under the root node of the solution.

If you nest your startup project in a solution folder, then Visual Studio will again, entirely capriciously, ignore it when automatically selecting a project as the startup project each time you delete the .vs directory.

Test projects must be given names that end in " Test". (Yes, that is a space.)

Usually, projects come in pairs: there is a production project, and a test project. Usually, we give the test project the same name as the production project, with a suitable suffix to indicate that this is a test project. If your production project is called "Covfefe", you might think that you have plenty of options to call your test project: "CovfefeTest", "Covfefe.Test", "Covfefe-Test", "Covfefe_Test", etc. Actually, none of these will work. You have to call it "Covfefe Test", with a space before "Test".

This is because the Visual Studio Solution Explorer uses different sorting rules from Windows File Explorer, so if you use anything but " Test" as a suffix for test projects you will find your projects listed in a different order between the Solution Explorer and the File Explorer. Depending on what you choose, your test projects will appear either before or after your production projects, either in Solution Explorer or in File Explorer, but not in both. The only trick I have been able to find which causes the test projects to always be listed after the production projects both in Solution Explorer and in File Explorer is to make each test project name consist of the production project name suffixed with " Test" (with a space.)

Solution items must be placed in a custom "_Solution Items" folder.

Solution-level items are a fiasco to begin with; they only exist because the Visual Studio Solution Explorer capriciously hides solution-level files from the user. Instead, Visual Studio offers the "Solution Items" workaround, which is a solution folder under the solution node where we can manually place links to solution-level files that we want to be able to access. (Because having to manually create links to your own files so that you can access them is always fun.)

This feature must never be used, and instead a custom solution folder must be created, called "_Solution Items". I am trying to remember exactly why I have decided that this should be done, it probably has to do with sorting, when I find out I will update this post.