In modern day, a majority of programmers have adopted git, npm, apt, snap, and whatever have you. There are some of us who care about the structure of repositories, and some who just stick a few hundred files in a directory, slap on cmake/make/.package/etc and call it good.

This topic is fairly obvious. Have you ever entered a massive repository with the aspiration to contribute, but couldn't find a single thing? Have you ever had to rely on git frontends search engines? Have you ever had to delve into issues/PRs because you couldn't find where a certain file was located? Have you ever walked away from a project with an 'ummm' because you broke your scroll wheel? Have you ever not been able to implement cmake in a relatively easy way due the sheer amount of files spread everywhere?

When you have a public non-read-only repository, it is guaranteed to grow. That is the beauty of open source and you should embrace free software. What can organization bring to you?

Subdirectories

If you use cmake or make, you are probably familiar with the appeal of having one subdirectory per target in a solution and shared in a separate subdirectory, built as a separate target.

Programs like cmake or make don't offer much support in the way of build trees and working directory support. This is a pity really, but as a developer I guarantee you've been to hell and back implementing cmake and make build files on top of your build tree. A developer's pipe dream is just to shove *.source into a single binary and it just pops out something usable. CMake is the worst of the two due to having next to zero implementation documentation - something you have to pick up from studying actual scripts.

Shortly said, you will likely want to eventually implement make or cmake so you should keep each target separate in a solution so that you can accurately reference shared reliably while having zero possibility to link or use files from other targets. Imagine the upkeep the Lua team has to go through. If you check out their makefile, you will note they have about 5 solutions [lua.exe, luac.exe, auxlib, lualib, lua.dll] built out of the root of the project. They use gcc -MM... to generate their tree and manually amend it to the makefile. Wouldn't it be nice to... you know... gcc -o lua.exe *.c -l...?

Entry Points

Clicking through a new repository, your first instinct probably is 'where is the main'. This goes hand and hand with two different, but similar points. File and Folder naming.

I'm sure you all want to stick your files in a folder called foo and call all your files bar-n.source, but did you know this is malpractice and a sin? Commit (get it) blasphemy no more!

You should conform with your language's file naming conventions when it comes to entry points. If you don't, users may end up including the wrong file, assuming your project is broken, and at worst npm uninstall your_repo. This is most notable in c, c++, javascript and python. It could be extended to many other languages. Please don't hide your entry point.

Leave a comment below with which folder you think holds the entry point to this program.