Make a project for whom are unfamiliar with your codebase

If you were given the task to create a project, which is primarily used by people who are temporarily on the project, how would you design it?

Think a little bit about before you read on!

Would you rather write a giant documentation explaining the "rocky parts" or would you rather create self explaining code? How would you make sure that people follow your best practices? How would you avoid needing to decline pull requests by letting people go on the wrong path?

Imagine yourself as a developer in a giant corporation who are given the task to add a feature to a repository they didn't even know about yesterday. From this viewpoint, you would be able to formulate your requirements.

Ready?

Here are my thoughts then!

The (very impartial and personal) list to Great Code

• the code should be obvious as much as it can be (aka Clean Code)
• the project should be very easy to start, 1 or 2 terminal commands only required, no Magic Scroll of Swift Running needed to be put in .bashrc
• there should be very nice snippets, templates available for other people that they can then copy-paste, or use as a standard
• code has clear expectations on its input and its output
• the data structure for each function should be obvious (I'm looking at you, Totally Dynamic Language With No Types)
• every element is searchable, any external dependency is clearly defined in a place that is making sense (you know what is not searchable? 'my-' + filenamepart1 + '-' + filenamepart2 + '.js')
• with the code being a connected graph every component can be reached in a logarithmic search kind of way, meaning you click on the highest level element, you see a list of meaningful choices, you can select the next level and the next until you arrive at the code you need to modify (see asterisk below)
• there are no folders with hundreds of files in them, everything is grouped neatly, there is also a clear thought on how to expand (I'm looking at you controllers and services and util folder with no attempt at grouping.)
• there is no witchcraft and magic recipes: "Only name your first born file index.js in a folder that has the suffix *-controller. In there, you must leave bread and wine for the Gods of Convention and you have to chant "Flaky test, flaky test! Fail me not, or else let the Devil ignore you!" three times, not more, not less! ... And don't forget to restart the Docker image running in the background."

*: Connected graph...? Logarithmically searchable code? Sorry, what...?

By connected graph I mean the ability to traverse the code in your IDE with Control/Command+Click (or whatever shortcut you use for Go to definition)

If you click on something and your IDE cannot resolve it, then your code is not a connected graph anymore.

"Utter garbage!" or "You missed..."

What's your opinion? How was the best repository you have had to work on? How was your experience working with codebase in a language you were barely familiar with?